Docs › Connectors › Connector configuration reference

Connector configuration reference

Every key of an astracode.mcp.servers entry, working examples, the project MCP files AstraCode reads, which entry wins, organisation servers, settings, timeouts and limits.

On this page

Connectors you add from the list are written into your settings for you. This page is for writing an entry by hand, and for knowing exactly what AstraCode reads. For adding, checking and approving connectors, see Connectors.

Where to write an entry

  1. Run AstraCode: MCP: Edit Servers from the command palette, or choose Open config under MCP servers on the Customize page. Your user settings open at astracode.mcp.servers.
  2. Add an entry to the list, using one of the examples below.
  3. Save. AstraCode starts the new server within a few seconds; watch its status on the Customize page.

An entry in your user settings applies in every folder, trusted or not. An entry in a project's workspace settings applies only in that project, only once the folder is trusted, and only after you approve it.

A server that runs on your machine

A command entry starts a program and talks to it over its standard input and output (stdio). This one runs the reference memory server through npx, and tells it where to keep its file:

settings.json

{
  "astracode.mcp.servers": [
    {
      "id": "memory",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"],
      "env": { "MEMORY_FILE_PATH": "/Users/you/.mcp/memory.jsonl" }
    }
  ]
}

Its tools reach the agent as mcp__memory__<tool>. The first start downloads the package, which can take a minute or two.

A server you reach by address

A url entry connects to a remote server over MCP's Streamable HTTP. If it needs a sign-in, AstraCode runs it through your browser the first time it is used. headers adds headers to every request:

settings.json

{
  "astracode.mcp.servers": [
    {
      "id": "linear",
      "url": "https://mcp.linear.app/mcp"
    },
    {
      "id": "internal",
      "url": "http://127.0.0.1:8808/mcp",
      "headers": { "X-Team": "platform" }
    }
  ]
}

A remote server that speaks only the older HTTP+SSE transport works too: give its address as the url. When the server refuses the first request with 400, 404 or 405, AstraCode switches to that transport by itself.

Every key

KeyTypeForWhat it does
idstring, requiredbothShort and unique. It becomes part of each tool's name, mcp__<id>__<tool>, so it may not contain __.
commandstringstdioThe program to run. An entry has a command or a url, never both.
argsliststdioIts arguments. Numbers and booleans are turned into strings.
envobjectstdioExtra environment variables, added over the editor's own environment. Numbers and booleans are turned into strings.
cwdstringstdioThe folder it runs in. The default is the first workspace folder, or your home folder when none is open.
urlstringremoteThe server's address: https://, or http:// only to localhost, 127.0.0.1 or [::1].
headersobjectremoteExtra headers on every request. An Authorization header is dropped: sign-in is negotiated and kept in your keychain.
enabledboolean, default truebothfalse keeps the entry listed, as turned off, but stopped.
type"stdio" or "http"bothOptional. Only checked against the rest of the entry: "http" without a url is refused.

Not accepted in astracode.mcp.servers

Tool names

Environment, PATH and working folder

A command server starts with the editor's environment plus your env. Opened from the Dock, Finder or a desktop menu, the editor may not have the PATH your shell sets up (Homebrew, nvm, asdf, ~/.local/bin), so npx or uvx can be missing. Put the full path in command; command -v npx in a terminal prints it. An organisation's server is the exception: it gets only the variables it needs to run and the ones its admin named.

Project MCP files

So a repository set up for another tool works here, AstraCode also reads the MCP files those tools keep, in every folder of the workspace, once the folder is trusted:

FileWritten byServers under
.mcp.jsonClaude CodemcpServers
.cursor/mcp.jsonCursormcpServers
mcp.json (project settings folder)Some editorsservers

Each is a map from a server's name, which becomes its id, to an entry with the keys above. Comments and trailing commas are allowed. A file that will not parse is reported in the connection log.

.mcp.json

{
  "mcpServers": {
    "db": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "${env:DATABASE_URL}"]
    },
    "docs": { "type": "http", "url": "https://docs.example.com/mcp" }
  }
}
Entry usesListed asChange it to
${input:...} (an editor's inputs)not supported: it asks for a value through an editor's "inputs" prompts...Put the value in an environment variable and write ${env:NAME}.
envFilenot supported: it reads its environment from an envFile...Name the variables in env, with ${env:NAME} for their values.
"type": "sse"not supported: it uses the older SSE transport...Use the server's Streamable HTTP address (often ending /mcp) with "type": "http". Or, if the server has only the older transport, put its address in your own astracode.mcp.servers, where the automatic fallback reaches it.

Which entry wins

Servers from every source run side by side. Where the same id is named in more than one place, the nearest usable, switched-on entry wins, in this order:

  1. The project's workspace settings (astracode.mcp.servers).
  2. The project's MCP files: per folder, .mcp.json, then .cursor/mcp.json, then the mcp.json in its settings folder.
  3. Your user settings.
  4. Installed plugins' servers.

The others are listed as overridden by the one in .... The same id twice in one place is a mistake rather than an override: the second is not started: a second server called "<id>" in <where>. An organisation's servers are always org-<id>, so they never clash with yours. In a folder you have not trusted, only your user settings count, and the connection log notes how many of the project's servers were not started.

Settings

SettingDefaultWhat it does
astracode.mcp.enabledtrueLoad tools from MCP servers at all. A project cannot switch this on in a folder you have not trusted.
astracode.mcp.servers[]Your servers, as above. A project's value is used only in a trusted folder, and each of its servers still asks for approval.
astracode.mcp.toolTimeoutSeconds120How long a tool call may go without an answer before it is given up on and the server is told to cancel it, from 10 to 3600. Each progress update the server sends starts the wait again, up to 60 minutes in all.

Timeouts and limits

WhatLimit
Starting a server and agreeing a protocol version10 seconds, or 120 seconds when the command is npx, uvx, bunx or pnpx, which may download first
Listing a server's tools10 seconds
Any other request to a server30 seconds
A tool callastracode.mcp.toolTimeoutSeconds, reset by progress, 60 minutes at most
Images in one tool result4, each up to about 3.75 MB
A tool's description1,000 characters
A line a stdio server writes8 MB; a server that writes more without a newline is stopped
Tools in one request128, or 200 when every model the run may use allows it; connector tools give way first
Redirects from a remote server5, and only to the same site

Protocol versions

AstraCode offers MCP 2026-07-28 first and also speaks 2025-11-25, 2025-06-18 and 2025-03-26, using the newest the server understands. Remote servers on the 2024-11-05 HTTP+SSE transport are reached through the automatic fallback. A server that speaks none of these fails with the versions it named. The client provides no sampling, roots or elicitation.

Organisation servers

An organisation's servers are written on the dashboard's Plugins page, under Servers, by an owner or admin: an Id, a Name, the Command, Arguments, one per line, and Environment variable names, one per line. They run a command; an organisation cannot list a url server. Never put a secret in the arguments: everyone in the organisation can read them, and each developer's own machine supplies the variables' values. How developers are asked: Servers your organisation offers.

The CLI's settings file

astracode-agent reads mcp.servers (with or without the astracode. prefix) from its own settings file: $ASTRACODE_CONFIG_DIR/settings.json, else $XDG_CONFIG_HOME/astracode/settings.json, else ~/.config/astracode/settings.json, on every system including Windows. It is never read from a project. The entry shape is the same:

~/.config/astracode/settings.json

{
  "mcp.servers": [
    {
      "id": "memory",
      "command": "/opt/homebrew/bin/npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    }
  ]
}

Only the full-screen conversation starts them. The CLI cannot complete a browser sign-in for a remote server, so a url server that needs one fails with server requires authorization; use a server that runs locally instead.

If something goes wrong

Each not started, not supported and failed reason, with its fix, is on Connector problems.

← Connectors (MCP servers) Use AstraCode from Claude, ChatGPT and other apps →

All documentation

Get started

Using the editor

Agent

Context

Workspaces

Connectors

Extending AstraCode

CLI

Account and usage

Troubleshooting

Reference