Discover and run MCP tools with ak:use-mcp

Use ak:use-mcp to discover an existing MCP server's tools, prompts, or resources and call the smallest tool that completes a bounded task. It prefers the active runtime's registered MCP surface and provides a deterministic local client for stdio servers declared in project configuration.

Choose ak:use-mcp for existing servers

Use ak:use-mcp when

• A registered MCP tool can read or change an external service for your task.
• You need to inspect tool names and input schemas before calling one.
• A project stdio server is configured but not visible in the current runtime.
• You need a persisted local catalog for a reproducible scripted workflow.

Choose another workflow when

• You need to design and implement a new server. Use ak:mcp-builder.
• You need the user's real Chrome cookies or exact profile. Establish that browser context before using a profile-blind DevTools server.
• The task does not require MCP. Use the narrower native tool or project command.
• You would need to copy credentials into another runtime's global config. Stop and configure the intended runtime explicitly instead.

Prepare access and choose a path

For runtime-native MCP, confirm the server and tool are visible in the current session. For the direct client, you need Node.js, npm, the bundled scripts, and a valid .claude/.mcp.json containing stdio command, args, and optional env for each server. Keep credentials in approved environment or secret stores.

Run the Skill

The Skill accepts a task and defines no mode flags. Name the server when known, state whether discovery must remain read-only, and identify any external write you are willing to approve.

/ak:use-mcp "List the issue tools available from the registered project server; do not call a mutating tool"

/ak:use-mcp "List the issue tools available from the registered project server; do not call a mutating tool"

$ak:use-mcp "List the issue tools available from the registered project server; do not call a mutating tool"

Use the bundled direct client only when needed

From the Skill's scripts/ directory:

npm install
npx tsx cli.ts list-tools
npx tsx cli.ts list-prompts
npx tsx cli.ts list-resources
npx tsx cli.ts call-tool <server> <tool> '<json-args>'

list-tools writes the discovered schemas to assets/tools.json. The client connects configured servers sequentially, continues when one server fails, uses a 120-second global CLI timeout by default through MCP_TIMEOUT, allows up to 300 seconds for individual list or call operations, and closes clients and transports when it finishes.

Understand the observable workflow

1. Inventory native capabilities. Search the current runtime before deciding a server is unavailable.
2. Choose the narrowest path. Use a native tool when visible; use the direct client only for a configured stdio server or deterministic CLI need.
3. Inspect the schema. Validate required arguments and constraints from the live tool definition or persisted catalog.
4. Classify effects. Distinguish discovery, read-only access, external writes, destructive actions, and calls that can incur provider cost.
5. Request approval when needed. Confirm the exact external mutation, destination, data, and expected cost before execution.
6. Call and report. Return the server/tool name, bounded arguments, result or error, and evidence of any changed external state.

Keep external effects explicit

Even list commands start configured server subprocesses, which may initialize network connections or provider clients. npm install downloads dependencies and creates local disk state. Tool calls may transmit inputs to external services, change remote data, consume quotas, or create charges according to the server and provider. Do not place secrets in command output or the catalog.

Verify outputs and evidence

A complete run identifies the selected path, discovered server and tool, validated argument schema, effect classification, approval record when needed, and returned result. For direct discovery, verify that assets/tools.json is valid JSON with server names and full input schemas. The bundled smoke test checks dependency availability, TypeScript compilation, CLI help, an empty configuration round trip, and restoration of the prior catalog; it does not exercise a live server.

Troubleshoot and limits

The direct client supports stdio configuration only, even though the MCP protocol and other clients can support remote transports. Its configuration reference describes environment loading more broadly than the bundled client implements, so rely on the actual process environment and server env mapping. The persisted catalog is a snapshot, not proof that tools remain available. The two release snapshots used for this page contain the same Skill and client.