auriti-labs/agentwork/mcp-integration

MCP Integration

Scope

Building MCP servers, configuring them in Kiro, debugging connection failures, and designing tool interfaces.

Triggers

• "build an MCP server" / "create MCP tools"
• "MCP failed" / "connection closed" / "server not starting"
• "add a tool to [server]" / "configure mcp.json"
• "integrate [system] via MCP"

When NOT to Use

• You're only calling existing MCP tools (just use them)
• You're building a REST/GraphQL API (not MCP)
• General Python/Node work without MCP involvement

Goals

• Produce a working MCP server that Kiro can connect to and use
• Ensure every tool has a clear name, description, typed parameters, and structured return
• Ensure the server starts reliably and survives Kiro session restarts

Constraints

• Always use absolute paths to interpreters in mcp.json (no relative, no bare python)
• Always test the server standalone before registering in Kiro
• Tool descriptions must say WHEN to use the tool, not just what it does
• Never crash the server on tool errors — return error messages in the result
• Tools must be idempotent (safe to retry)

Input Minimi

• What the server does (purpose, tools to expose)
• Language: Python (mcp SDK) or Node (@modelcontextprotocol/sdk)
• Transport: stdio (local, default) or HTTP (remote)

Checklist

Build

1. Create server with SDK (see examples/python-mcp-server.md or examples/node-mcp-server.md)
2. Register tools with typed parameters and trigger-oriented descriptions
3. Test standalone with JSON-RPC init message
4. Register in ~/.kiro/settings/mcp.json with absolute paths
5. Verify in Kiro: /mcp should show server as "running"

Debug

1. Check /mcp in Kiro for status
2. Run the exact command from mcp.json manually in terminal
3. If it crashes: check imports, dependencies, Python version (≥3.11 for most SDKs)
4. See references/mcp-debugging.md for the full error→cause→fix table

Add to Agent JSON

"mcpServers": {
  "my-server": {
    "command": "/absolute/path/to/python",
    "args": ["/absolute/path/to/server.py"],
    "timeout": 120000
  }
},
"tools": ["@my-server"],
"allowedTools": ["@my-server/my_tool"]

Gotchas

1. Bare `python` in mcp.json breaks across environments. Always use the full venv path: /home/user/project/.venv/bin/python. Kiro doesn't activate venvs.

1. Server starts but tools don't appear. The tool decorator ran but server.run() wasn't called, or the server exited before Kiro could list tools. Test with the full init→initialized→tools/list sequence.

1. `connection closed: initialize response` means the server crashed during init, not that the protocol failed. Run the server manually and look at stderr. 99% of the time it's a missing import or wrong Python version.

1. Node servers need `node_modules` in the right place. If mcp.json points to dist/server.js, npm dependencies must be resolvable from that directory. Run npm ls @modelcontextprotocol/sdk from the server's directory to verify.

1. FTS5 corruption in SQLite-backed MCP servers is silent. The server starts, health checks pass, but search tools return errors. Test actual tool calls, not just /mcp status.

1. Kiro restarts all MCP servers on every session start. If your server has slow imports (ML models, large DBs), startup will timeout. Lazy-import heavy dependencies or increase timeout beyond 120000.

1. `console.log` in Node MCP servers corrupts the stdio protocol. Redirect all logging to stderr: console.log = (...args) => console.error("[my-server]", ...args).

Handoff

• After server built → kiro-qa for code review
• After configured → test with /mcp in Kiro
• If server is a CLI tool → load python-cli-tooling skill
• If server manages agent memory → load memory-systems skill

Memory Guidance

TotalRecall: mcp.json configurations that worked, debugging steps for specific failures, tool schema designs that proved effective Kore candidates: Server templates that work across projects, debugging patterns (error→cause→fix), tool design patterns Never save: SDK boilerplate, standard mcp.json syntax, obvious pip/npm commands

When to Read Support Files

• Building a new server? Read examples/python-mcp-server.md or examples/node-mcp-server.md for a complete working template
• Debugging a failure? Read references/mcp-debugging.md for the full error→cause→fix table
• Designing tool interfaces? Read references/mcp-tool-design.md for naming, schema, and description rules
• Choosing architecture? Read references/mcp-server-patterns.md for transport, worker, and deployment patterns