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
- Where to write an entry
- A server that runs on your machine
- A server you reach by address
- Every key
- Not accepted in astracode.mcp.servers
- Tool names
- Environment, PATH and working folder
- Project MCP files
- Which entry wins
- Settings
- Timeouts and limits
- Protocol versions
- Organisation servers
- The CLI's settings file
- If something goes wrong
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
- 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. - Add an entry to the list, using one of the examples below.
- 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
| Key | Type | For | What it does |
|---|---|---|---|
id | string, required | both | Short and unique. It becomes part of each tool's name, mcp__<id>__<tool>, so it may not contain __. |
command | string | stdio | The program to run. An entry has a command or a url, never both. |
args | list | stdio | Its arguments. Numbers and booleans are turned into strings. |
env | object | stdio | Extra environment variables, added over the editor's own environment. Numbers and booleans are turned into strings. |
cwd | string | stdio | The folder it runs in. The default is the first workspace folder, or your home folder when none is open. |
url | string | remote | The server's address: https://, or http:// only to localhost, 127.0.0.1 or [::1]. |
headers | object | remote | Extra headers on every request. An Authorization header is dropped: sign-in is negotiated and kept in your keychain. |
enabled | boolean, default true | both | false keeps the entry listed, as turned off, but stopped. |
type | "stdio" or "http" | both | Optional. Only checked against the rest of the entry: "http" without a url is refused. |
Not accepted in astracode.mcp.servers
"disabled": true. In your settings, use"enabled": false. (disabledis honoured only in a project MCP file.)- Variables such as
${env:NAME},${workspaceFolder}or${userHome}. They are written to the server as they are. Expansion happens only in project MCP files. envFile, and an editor'sinputsprompts.- An
Authorizationheader, or a token anywhere in the entry. Use the connector's sign-in, or Set token for a connector from the list. - Plain
http://to anything but this machine.
Tool names
- Each tool is named
mcp__<id>__<tool>, at most 64 characters. A name that would be longer, or that would collide with another, gets a short hash at the end. - An
idcontaining__is refused:its id "<id>" contains "__", which separates the server from the tool in a tool name; rename it. - Two ids that become the same prefix once cleaned up, such as
my.serverandmy_server, cannot both run; the second is skipped and the connection log says so.
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:
| File | Written by | Servers under |
|---|---|---|
.mcp.json | Claude Code | mcpServers |
.cursor/mcp.json | Cursor | mcpServers |
mcp.json (project settings folder) | Some editors | servers |
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" }
}
}
- In these files only,
${env:NAME},${workspaceFolder}and${userHome}are expanded. The approval prompt shows the entry as written, never with a value expanded into it. "disabled": trueand"enabled": falseboth turn an entry off.- Each server needs your approval on this machine for this workspace before it starts. See A project's own servers.
| Entry uses | Listed as | Change 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}. |
envFile | not 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:
- The project's workspace settings (
astracode.mcp.servers). - The project's MCP files: per folder,
.mcp.json, then.cursor/mcp.json, then themcp.jsonin its settings folder. - Your user settings.
- 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
| Setting | Default | What it does |
|---|---|---|
astracode.mcp.enabled | true | Load 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.toolTimeoutSeconds | 120 | How 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
| What | Limit |
|---|---|
| Starting a server and agreeing a protocol version | 10 seconds, or 120 seconds when the command is npx, uvx, bunx or pnpx, which may download first |
| Listing a server's tools | 10 seconds |
| Any other request to a server | 30 seconds |
| A tool call | astracode.mcp.toolTimeoutSeconds, reset by progress, 60 minutes at most |
| Images in one tool result | 4, each up to about 3.75 MB |
| A tool's description | 1,000 characters |
| A line a stdio server writes | 8 MB; a server that writes more without a newline is stopped |
| Tools in one request | 128, or 200 when every model the run may use allows it; connector tools give way first |
| Redirects from a remote server | 5, 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
- Tab completion
- Edit and ask about a selection
- Reviewing the agent's changes
- Git: commit messages, branch review and conflicts
- Dictation
- Layout, themes and the settings page
Agent
- Agent overview
- Agent, Plan, Ask and Debug
- Approvals and permissions
- Plan mode
- Debug mode
- Tools
- Browser tools
- How the agent checks its work
- Checkpoints and undo
- Running several agents at once
- Subagents and background tasks
- Remote agents in GitHub Actions
- Infrastructure as code
Context
Workspaces
Connectors
- Connectors (MCP servers)
- Connector configuration reference
- Use AstraCode from Claude, ChatGPT and other apps
Extending AstraCode
CLI
Account and usage
- Usage and limits
- Bring your own key
- What AstraCode sends and keeps
- Reporting a problem and getting help
Troubleshooting
- Troubleshooting
- Sign-in problems
- Install and update problems
- Chat panel problems
- Agent run problems
- Connector problems
- Dictation problems
- Usage, billing and network errors
- CLI problems