Skip to content

mcp.md

Latest commit

 

History

History
180 lines (144 loc) · 3.75 KB

mcp.md

File metadata and controls

180 lines (144 loc) · 3.75 KB
Raw

MCP Servers

Architect supports the Model Context Protocol (MCP) for connecting external tool servers. MCP servers expose additional tools that the model can use alongside Architect's built-in tools.

Configuration

MCP servers are configured in .mcp.json files:

  • Global: ~/.architect/.mcp.json -- available in all projects
  • Project: .mcp.json in the project root -- scoped to that project

Both files are loaded and merged. Project servers override global ones with the same name.

Schema

{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/data"],
      "env": {
        "API_KEY": "${MY_API_KEY}"
      }
    }
  }
}

Server Types

Stdio (Local)

Launches a local process and communicates via stdin/stdout:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
    },
    "sqlite": {
      "command": "uvx",
      "args": ["mcp-server-sqlite", "--db-path", "./data.db"]
    }
  }
}
Field Required Description
command Yes Executable to launch
args No Command-line arguments
env No Environment variables for the process

HTTP (Remote)

Connects to a remote MCP server over HTTP:

{
  "mcpServers": {
    "remote-tools": {
      "url": "https://mcp.example.com/tools",
      "headers": {
        "Authorization": "Bearer ${MCP_TOKEN}"
      }
    }
  }
}
Field Required Description
url Yes Server endpoint URL
headers No HTTP headers (e.g., authentication)

SSE (Server-Sent Events)

Legacy transport -- same schema as HTTP but uses SSE for streaming:

{
  "mcpServers": {
    "sse-server": {
      "url": "https://mcp.example.com/sse",
      "headers": {}
    }
  }
}

Environment Variable Expansion

All string values in the config support environment variable substitution:

Syntax Behavior
${VAR} Expands to the value of VAR. Empty if unset
${VAR:-default} Expands to VAR if set, otherwise default 
{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["${HOME}/tools/server.js"],
      "env": {
        "API_KEY": "${MY_API_KEY:-sk-default}",
        "PORT": "${MCP_PORT:-3001}"
      }
    }
  }
}

Server Status

MCP servers can be in one of these states:

Status Meaning
Connected Successfully connected, tools available
Failed Connection error (logged with details)
Disabled Server disabled in config
Disconnected Not yet connected

How It Works

  1. On startup, Architect reads .mcp.json files
  2. Connects to each configured server
  3. Discovers available tools via the MCP protocol
  4. Registers discovered tools alongside built-in tools
  5. The model can use MCP tools like any other tool

MCP tools follow the same permission system as built-in tools. Tool names from MCP servers are prefixed with the server name to avoid conflicts (e.g., filesystem:read_file).

Examples

Filesystem Access

{
  "mcpServers": {
    "fs": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/data"]
    }
  }
}

Database Access

{
  "mcpServers": {
    "db": {
      "command": "uvx",
      "args": ["mcp-server-sqlite", "--db-path", "./app.db"]
    }
  }
}

Custom API Server

{
  "mcpServers": {
    "internal-api": {
      "url": "https://internal.company.com/mcp",
      "headers": {
        "Authorization": "Bearer ${INTERNAL_TOKEN}"
      }
    }
  }
}