MCP Servers

MCP servers give the agent extra tools, such as querying a database, reading GitHub issues or calling your company's internal APIs. Andromity connects to local servers that it starts as a process (stdio) and to remote servers over HTTP or SSE.

Add a server in VS CodeCopy Anchor Link

1. Open Settings → MCP Servers and select Add MCP Server.

2. Enter a Server name.

3. Choose a connection type:

   Type	You enter
   Remote HTTP (OAuth or access token)	The server URL, then an optional access token. Leave the token empty to sign in with your browser after adding.
   Remote SSE (legacy)	The same, for servers that only speak SSE.
   Local command (stdio)	The command (such as npx, uvx or python), then its arguments as a JSON array, for example ["-y", "@modelcontextprotocol/server-filesystem", "."].
   Advanced JSON configuration	One server object, for when you need env, headers or oauth.client_id.

Andromity saves the server to <project>/.andromity/mcp.json and connects to it. Adding and removing servers needs an open, trusted workspace.

Each server card shows its status, its command or URL, and View tools (N) once connected. Card buttons:

• ↺ Restart: reconnect (enable the server first if it's disabled).
• Enable / Disable: sets "disabled" in the config file. Disabled servers are not started.
• Connect / Authenticate or Re-authenticate: for remote servers (see Authentication).
• Remove: deletes the server from its config file, with its saved sign-in, after you confirm.

When a server fails, the card shows the error and the last 25 lines the server wrote to stderr.

Add a server in the terminal appCopy Anchor Link

Open Settings (Ctrl+E) → MCP → + Add Server, fill in the form and select Save & Connect. It also writes to <project>/.andromity/mcp.json.

/mcp prints every configured server with its status and the tools it provides.

Config filesCopy Anchor Link

Andromity reads these files, in this order:

If two files define a server with the same name, the first one wins, so your user-level definition overrides the project's.

Servers go under mcpServers (servers is also accepted):

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost:5432/dev"],
      "env": { "PGPASSWORD": "dev-only-password" }
    },
    "supabase": {
      "url": "https://mcp.supabase.com/mcp?project_ref=YOUR_PROJECT_REF",
      "type": "http"
    },
    "internal-api": {
      "url": "https://mcp.example.internal/sse",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    },
    "paused": {
      "command": "uvx",
      "args": ["some-mcp-server"],
      "disabled": true
    }
  }
}

Things to know:

• Values are used as written. ${VAR} and ${input:...} are not expanded. Put secrets in your user-level file rather than in a project file you commit.
• Local servers start in the project folder. They inherit Andromity's environment plus env, but never your provider API keys (ANTHROPIC_API_KEY, OPENAI_API_KEY and the others listed in API keys).
• Automatic transport: a URL whose path ends in /sse uses SSE; anything else uses streamable HTTP and falls back to SSE if the server answers 404 or 405.
• mcp-remote commands (for example npx -y mcp-remote https://... --header "Authorization:Bearer TOKEN") are treated as remote servers: Andromity connects to the URL directly, sends each --header as an HTTP header, and ignores the other arguments.
• If you edit a file by hand, select Refresh in Settings → MCP Servers to show the change, then ↺ Restart on the server to connect with its new settings.

AuthenticationCopy Anchor Link

For a remote server that needs sign-in, select Connect / Authenticate on its card and choose:

• Sign in with browser (OAuth): Andromity uses OAuth 2.1 with PKCE. It discovers the server's authorization settings and registers itself as a client, or uses oauth.client_id if the server requires a pre-registered client. Your browser returns to http://127.0.0.1:<port>/callback (ports from 54321 up), and you have 2 minutes to finish.
• Use access token / PAT: paste a personal access token. In the terminal app, use 🔑 Use PAT on the server's card.

Tokens are saved in ~/.andromity/tokens.json, encrypted with Windows DPAPI on Windows and readable only by you (600) elsewhere. OAuth tokens are refreshed automatically. A saved token replaces any Authorization header in the config.

How the agent finds MCP toolsCopy Anchor Link

MCP tools are named mcp__<server>__<tool>, for example mcp__github__create_issue.

Their full parameter schemas are not sent with every request. Instead, the system prompt lists each MCP tool's name and description:

<available-deferred-tools>
• mcp__github__create_issue: [github] Create a new issue in a GitHub repository
Use list_tools() to retrieve the full catalog or specific schemas before calling any deferred tool.
</available-deferred-tools>

Before calling one, the agent uses the built-in list_tools tool (with search and include_description) to read its parameters. This keeps the request small when you connect many servers, but each tool's description is still in the prompt. To see what your servers cost, open the context indicator under the prompt box in VS Code and look at MCP & deferred tools. Disable servers you aren't using.

The tool list comes from each server when it connects, so restart a server after updating it.

Approvals and folder trustCopy Anchor Link

• Untrusted folder: MCP servers are not started, including ones from your user-level file, and their status is Untrusted folder. MCP tools are blocked in every mode. Trust the folder to connect them.
• SAFE: every MCP tool call asks for approval.
• TRUST: a call asks when the tool's own name (not the server's) contains write, insert, update, delete, create, drop, push, exec or post. Other calls run. For example, mcp__github__create_issue asks and mcp__postgres__query runs.
• FULL and YOLO: MCP tools run without asking.

Tool annotations such as readOnlyHint are not used. Edits the agent makes to .andromity/mcp.json or .vscode/mcp.json always ask outside FULL and YOLO, because .andromity and .vscode are execution-control folders.

When servers startCopy Anchor Link

All configured servers start together when the Andromity engine starts, and restart when you switch project. If any need attention, VS Code shows MCP servers need attention with Open MCP Settings. The terminal app reports how many servers and tools are ready.

Servers that crash are not restarted automatically; their card shows error with the exit code. Select ↺ Restart.

Headless runs with andromity run don't load MCP servers.

TroubleshootingCopy Anchor Link