using-mcp

# MCP Tools Calling Skill

Use this skill whenever you need to talk to an MCP server: list servers, connect to one, inspect a tool's schema, or invoke a tool.

## How it works

The six MCP capabilities are exposed as Code Mode tools (`mcp_*`). They are NOT directly callable as standalone tool calls. You must invoke them through `run_sdk_snippet` and `sdk.tool.call`:

```python
run_sdk_snippet(python_code="""
from sdk.tool import tool

result = tool.call('mcp_list_servers', {})
print(result.content)
""")
```

`tool.call(name, params)` returns a `Result` with:
- `result.ok` — boolean, check this first
- `result.content` — complete information for reasoning and next-step decisions

## Available MCP tools

| Tool name | Purpose |
|-----------|---------|
| `mcp_list_servers` | List all MCP servers in the current chat with their connection status. Always start here. |
| `mcp_connect_server` | Connect a server whose status is `disconnected`. Returns the real tool list. |
| `mcp_list_tools` | List tools across connected servers, optionally filtered by `server_name`. |
| `mcp_get_tool_schema` | Fetch the JSON input schema of one or more tools before calling them. |
| `mcp_call_tool` | Invoke a specific tool on a server. The actual remote call. |
| `mcp_add_server` | Register a new MCP server config (stdio or http). Does NOT connect immediately. |
| `mcp_remove_server` | Remove an MCP server: disconnect, unregister tools, and delete persisted config. |

## Standard workflow

Follow this order. Skipping steps will cause failures because tool names and parameters cannot be guessed.

```
1. mcp_list_servers          → pick the server, read its `status`
   ├── status == 'connected'    → go to step 3
   └── status == 'disconnected' → go to step 2
2. mcp_connect_server        → connect; receive the real tool list
3. mcp_get_tool_schema       → fetch input schema(s)
4. mcp_call_tool             → invoke with parameters that match the schema
```

When the user wants to register a brand-new MCP server, run `mcp_add_server` first, then proceed from step 1.

## Rules

1. NEVER fabricate server names, tool names, or parameter names. Always derive them from the previous step's `result.content`.
2. ALWAYS call `mcp_get_tool_schema` before `mcp_call_tool` unless you already saw the schema in this conversation.
3. NEVER call `mcp_*` tools as standalone tool calls. They only work inside `run_sdk_snippet` via `sdk.tool.call`.
4. ALWAYS check `result.ok` before proceeding. Errors should be surfaced to the user, not silently retried.

## Environment variables in reusable MCP configs

MCP configs can be written as reusable templates in skills. Put sensitive
values behind `${VAR_NAME}` placeholders, and ask the user to save their own
value with env-manager before registering or connecting the MCP server.

Supported placeholder locations:

- `url`, including query parameters: `https://mcp.example.com/sse?key=${EXAMPLE_API_KEY}`
- `headers` values: `{"x-api-key": "${EXAMPLE_API_KEY}"}`
- `token`
- stdio `env` values: `{"EXAMPLE_API_KEY": "${EXAMPLE_API_KEY}"}`

Do not put personal API keys directly in skill docs or MCP config templates.
If a referenced env variable is missing or unusable, connecting the MCP server
fails with the missing variable name. The secret value is not written into the
persisted MCP config.

Only the fields above are resolved. Do not use `${VAR_NAME}` in `name`,
`description`, `command`, or `args`.

## End-to-end example

User asks to call a tool on some MCP server. The flow below uses angle-
bracket placeholders (`<server_name>`, `<tool_name>`, `<workspace_dir>`,
etc.); replace every `<...>` with the real value from your context or from
the previous step before running the snippet.

```python
run_sdk_snippet(python_code="""
from sdk.tool import tool

# 1. Discover servers
servers = tool.call('mcp_list_servers', {})
print(servers.content)
# Parse the server name from content, e.g. "<server_name> (status=connected, N tool(s))"

# 2. Connect if needed
connect = tool.call('mcp_connect_server', {'server_name': '<server_name>'})
if not connect.ok:
    raise SystemExit(f'Connect failed: {connect.content}')
print(connect.content)

# 3. Inspect schema
schema = tool.call('mcp_get_tool_schema', {
    'server_name': '<server_name>',
    'tool_name': '<tool_name>',
})
print(schema.content)

# 4. Call the tool (tool_params is a JSON string matching the schema)
result = tool.call('mcp_call_tool', {
    'server_name': '<server_name>',
    'tool_name': '<tool_name>',
    'tool_params': '{"key": "value"}',
})
print(result.content)
""")
```

## Saving the call result to a file (`output_file_path`)

`mcp_call_tool` accepts an optional `output_file_path` to persist the result
as a JSON file in the workspace, instead of consuming it only in your
reasoning context.

When to set it:

- The result is likely to be large (for example a SQL query without WHERE or
  LIMIT that may return thousands of rows, fetching a full article body, or
  exporting a long list).
- The user expects a concrete file deliverable (a report, dataset dump,
  attachment-like artifact).
- A downstream step needs a stable on-disk path to open later.

When to leave it empty:

- You only need the data for your own reasoning. Small results are returned
  inline; oversized results are auto-persisted in the background to avoid
  flooding the context, so you do not need to manage that yourself.

Rules:

1. The path MUST be absolute. Relative paths are rejected and the call
   silently falls back to the runtime directory.
2. Prefer a location inside the current workspace so the file is easy for
   the user to inspect and accept as a deliverable. The workspace path is
   already available in your context — just prepend it directly, e.g.
   `<workspace_dir>/data/<server>/<tool>.json`. Do not rebuild it from
   `os.getcwd()` or hard-code a path from another machine.
3. The file MUST be JSON. Pick a meaningful filename and a tidy directory
   layout, for examp