adding-external-mcp

Adding External MCP — canonical reference

The full, ground-truth procedure for adding a NEW external MCP server to Tlamatini universal MCP client layer. This skill makes Tlamatini autonomously capable of adding, configuring, activating, and verifying any external MCP server — robustly and bullet-proof.

What this skill does

Enables Tlamatini to add ANY external MCP server to her universal MCP client layer — the system that lets her use tools from arbitrary MCP servers declared in a JSON catalog (external_mcps.json), with no code per server.

Architecture overview

external_mcps.json (catalog) --> external_mcp_manager.py --> ext__<server>__<tool>
      |
      |-- _StdioMcpClient (local child)
      |-- _StreamableHttpMcpClient (HTTP)
      |-- _SseMcpClient (legacy SSE)
      |-- _WebSocketMcpClient (WS)
      |
      |-- external_mcp_defaults.py (code-owned defaults: memory, sequential-thinking)
      |-- runtime_provisioner.py (private npx/uvx/node provisioning)

Key constants: MAX_ACTIVE = 5 | _SUPPORTED_TRANSPORTS = {stdio, streamable-http, sse, websocket}

Procedure — adding a new external MCP server

Step 1 — Classify the server transport

Determine which transport the MCP server uses:

Transport	When to use	Config key
stdio	Local child process (npx, uvx, docker, python)	command + args
streamable-http	HTTP endpoint (modern MCP servers)	url
sse	Legacy Server-Sent Events endpoint	url
websocket	WebSocket endpoint	url

If the server provides a .mcp.json or equivalent config, copy it directly — the catalog uses the same mcpServers shape as Claude Code.

Step 2 — Build the server config

The server config is a JSON object with these fields:

{
  "command": "npx",
  "args": ["-y", "@some/mcp-server"],
  "env": { "API_KEY": "<REDACTED>" },
  "transport": "stdio",
  "description": "Optional human-readable description"
}