mcp-runner

Files (1)

• SKILL.md

SKILL.md (first lines)

# mcp-runner

Use [`mcporter`](https://mcporter.dev) to work with MCP servers from the sandbox. mcporter handles HTTP + stdio transports, OAuth, and JSON-RPC envelopes — you don't construct any of that by hand.

If `mcporter` isn't already on PATH (`command -v mcporter`), invoke it through `npx mcporter` — the sandbox image includes Node + npm.

## Discover servers + tools

```sh
mcporter list                            # configured servers
mcporter list <server> --schema          # tools on a server, with input schema
mcporter call <server.tool> --schema     # one tool's schema only
```

Pass `--output json` whenever you need to parse the result — bare CLI output is human-formatted and not parsing-stable.

## Call tools

```sh
mcporter call linear.list_issues team=ENG limit:5         # selector form
mcporter call "linear.create_issue(title: \"Bug\")"       # function form
mcporter call <server.tool> --args '{"limit":5}'          # JSON args, when the CLI forms get awkward
```

Stdio servers (binary runs the MCP server in-process):

```sh
mcporter call --stdio "bun run ./server.ts" scrape url=https://example.com
```

Full HTTP URL when no named server is configured:

```sh
mcporter call https://api.example.com/mcp.fetch url:https://example.com
```

## Auth + config

```sh
mcporter auth <server | url>            # initial OAuth (browser flow won't work in headless sandboxes — the org admin runs this once and the token persists)
mcporter auth <server> --reset          # rotate
mcporter config list|get|add|remove     # inspect / mutate the config store
mcporter config login|logout            # mcporter-side identity, not server-side
```

Default config: `./config/mcporter.json`. Override via `--config <path>` when the org has provisioned a non-default location.

## Translate errors plainly

- `command not found: mcporter` → retry with `npx mcporter <same args>`. Don't ask the user to install anything.
- HTTP 401 / 403 from the server → the token expired or was revoked. Tell the user which server, suggest `mcporter auth <server>` to re-authenticate.
- mcporter prints structured tool errors as JSON when the tool itself fails — surface the `message` field verbatim to the user, don't paraphrase.
- Missing config / env vars → explain what's missing rather than retrying blindly.

## When NOT to use this skill

- Tasks that don't involve a named MCP server. Use the regular toolset (bash, read, write, fetch, grep, glob).
- Plain HTTP APIs that aren't MCP. Use the `fetch` tool — it parses responses and respects body size limits.
- Anything destructive (create, delete, send) without explicit user confirmation. Most MCP servers expose write tools; confirm first.

From iarmankhan/zuno, MIT.

More from iarmankhan/zuno