---
name: mcp-tools
description: "Working on Python plugin tools, MCP server connections, tool invocation, or tool tracing. Primary task is tasks/0007-mcp-tools-and-permissions.md."
generated: true
source: .ai/skills/mcp-tools.md
---

<!--
This file is generated by tools/skills.
Do not edit this file directly.
Edit .ai/skills/mcp-tools.md and run `make generate-ai`.
-->

# Skill: MCP & Tools

## When to use this skill

Use this when working on Python plugin tools, MCP server connections, tool
invocation, or tool tracing. Primary task:
`tasks/0007-mcp-tools-and-permissions.md`.

## Files to read first

- `AGENTS.md`
- `docs/MCP_AND_TOOLS.md`
- `docs/RUNTIME_LIFECYCLE.md`

## Architecture rules

- Resolver plugins run before a node; tool plugins are exposed to the LLM during
  execution.
- MCP clients are created once and shared; never per request.
- Per-request data flows via `ExecutionContext` / `ctx`.
- Prompt text is not a security boundary.
- Secrets never live in YAML; they are redacted in traces.

## Implementation rules

- Implement tool registry and MCP integration in `src/agentplatform/tools`.
- Load plugin classes once where possible.
- Invoke configured class/method references with `ctx`.
- Validate tool and MCP ids during validation/compilation; runtime should use
  resolved bindings.
- Hold MCP clients on the long-lived runtime.

## Validation checklist

- [ ] Tool plugin references load and invoke through the registry.
- [ ] MCP connections are created once and reused.
- [ ] Per-request context does not leak through shared state.
- [ ] Tool/MCP calls are traced with redaction.
- [ ] Tests cover success and failure with fakes.
- [ ] `make check` passes.

## Common mistakes to avoid

- Recreating MCP connections per request.
- Treating resolvers as tools or tools as resolvers.
- Skipping trace redaction.
- Relying on prompt wording for enforcement.