---
name: codemode-how-to-mcp
description: 'Reach external services, such as GitHub, through the MCP servers the person configured. Use whenever a task needs an MCP tool; loading it lists the servers and tools this session can call.'
---

# Use MCP from code mode

MCP servers are configured outside Po. In code mode each server tool is a method on the `mcp` namespace: `mcp.<server>.<tool>(args)`. The servers and tool names this session can call are listed at the end of this skill when you load it with `load_skill`. For anything else, ask `discover`.

## Find a tool

- `discover({ query: 'github/search_issues' })` returns one tool's signature, its input fields and what it returns. Run it before the first call to a tool.
- `discover({ namespace: 'mcp' })` returns every signature. A large catalog is cut at 24,000 characters, so narrow with `query`.
- Use only the server and tool names the list or `discover` shows. Never guess a name or an argument.
- The list below is a snapshot from when the skill loaded. After `/mcp reload` or a new sign-in, `discover` is the source of truth.

## Call it

```ts
const found = await mcp.github.search_issues({ query: 'is:open label:bug' });
return found.structuredContent ?? found.text;
```

- Names are the exact configured server and original tool names. Use brackets when a name is not an identifier: `mcp['work-github']['search-issues'](args)`. `mcp.call(server, tool, args)` is the same call by string.
- A result is `{ text, images, structuredContent?, blocks? }`. `structuredContent` is typed when the server declares an output schema. Pass a result to `image()` to see its images.
- An upstream error rejects with the server's text. Wrap a call in `try` to keep going, or use `Promise.allSettled` for a batch.
- Nothing is printed unless the script returns it. Return the fields you need, not the whole result.

## Tools that change data ask first

A tool counts as changing data unless its server marks it read-only (`readOnlyHint: true`) or not destructive (`destructiveHint: false`). Most servers mark nothing, so most tools ask. `discover` labels them `(asks first)`.

- Call such a tool through its typed member, `mcp.<server>.<tool>(args)`. The script does not wait: the call throws a pending-approval error, the rest of the script keeps running, and the call runs once the person approves. Its outcome arrives as a message, so do not retry it and do not depend on its result later in the same script.
- `mcp.call(server, tool, args)` refuses a tool that asks first. Use the typed member instead. A tool whose server or tool name contains a dot or a space cannot carry a prompt in code mode; call its direct tool.
- The person can let these tools run without asking: in MCP settings for every session, or with `/mcp approve on` for this session only. Never ask them to turn it on to save you a step.
- Subagents, background runs and other unattended calls are not asked: they run directly.
- A server that is removed, disconnected, signed out or failing leaves this list, `discover` and the direct tools until it reconnects. If a tool you used earlier is gone, check `/mcp status` instead of guessing a new name.

## Batch

Independent calls go in one `exec` with `Promise.all`. Several servers can answer in a single script:

```ts
const [issues, docs] = await Promise.all([
  mcp.github.search_issues({ query: 'is:open' }),
  mcp.notion.search({ query: 'roadmap' }),
]);
return { issues: issues.structuredContent, docs: docs.text };
```

## Limits and mistakes

- `exec` stops at 30 seconds by default. Pass `timeoutMs` up to 120,000 for slow tools. Time spent waiting for file-upload consent counts against it.
- With code mode on, you have no direct tool such as `github_search_issues`: its schema would only cost context, so the namespace is the way in, and `discover` shows the signature. That includes a tool that carries an MCP App: call it from `exec` and its App opens on that call's card for the person. A call from `exec_background` keeps its result but shows no App.
- If the tool set changes while a script runs, the call fails with "MCP tools changed". Run `discover` again and retry in a new `exec`.
- Ordinary MCP calls cannot reload configuration or read credentials. Use `/mcp auth <server>` and `/mcp reload` for configured servers. In Help mode, discover `mcpTest` to add a session-only URL server and await sign-in; see `help-how-to-mcp`. Ask permission before connecting.
