| name | ak:use-mcp |
| description | Discover and execute MCP server tools through runtime-native capabilities or deterministic direct scripts. Use for MCP integrations, controlled tool execution, capability discovery, and persistent tool catalogs. |
| user-invocable | true |
| when_to_use | Invoke for MCP tool discovery or controlled tool execution. |
| category | dev-tools |
| keywords | ["MCP","tools","execute","discovery","mcp-client"] |
| argument-hint | [task] |
| metadata | {"author":"agentkit","version":"2.0.0"} |
MCP Tool Discovery & Execution
Use the narrowest supported MCP path for the task:
| Path | When | Trade-off |
|---|
| Runtime-native MCP | The active Claude Code or Codex runtime already exposes the server/tool. | Lowest setup and context cost; visibility is limited to registered servers. |
| Direct Scripts | A server exists only in .claude/.mcp.json, or the task needs a deterministic tool name and argument shape. | Explicit and reproducible; requires local dependencies. |
Path 1: Runtime-native MCP (primary)
- Inspect the MCP resources and tools already registered with the active runtime.
- Select the smallest tool that directly satisfies the task.
- Validate required arguments before execution.
- Keep mutations within the user's requested scope.
Claude Code and Codex expose different native tool names. Use the actual tools
visible in the current session rather than assuming a shared spelling. If the
runtime supports deferred tool discovery, search for the server or capability
before concluding that it is unavailable.
Path 2: Direct Scripts
The scripts/ directory ships a self-contained MCP client built on
@modelcontextprotocol/sdk. Use it for servers declared in
.claude/.mcp.json that are not registered with the active runtime, or for
deterministic scripted/CI workflows.
cd scripts && 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 persists the catalog to assets/tools.json
with full schemas. Review that catalog before calling a tool when the name or
argument shape is unknown.
Module Layout
| File | Role |
|---|
scripts/mcp-client.ts | Config loader, multi-server connector, list/call wrappers, lifecycle cleanup |
scripts/cli.ts | list-tools, list-prompts, list-resources, call-tool, signal handling, timeout |
scripts/package.json | Pinned SDK and TypeScript runtime dependencies |
scripts/smoke-test.sh | End-to-end smoke test with no live server required |
assets/tools.json | Persisted tool catalog regenerated by list-tools |
Important Notes
- Runtime-native tools only see servers registered with that runtime.
- Direct scripts read
.claude/.mcp.json; do not silently copy credentials into another runtime's global config.
- Chrome DevTools MCP is profile-blind. For work requiring real Chrome cookies or an exact profile, invoke
ak:chrome-profile first and bind to the returned page selector.
mcp-builder creates new servers. It is not a fallback for consuming an existing server.- The retired Gemini CLI path is not supported. See the compatibility note at
references/gemini-cli-integration.md.
Technical Details
