Docs › Connectors

Connectors (MCP servers)

Give the agent tools from other systems (issue trackers, databases, internal APIs) through the Model Context Protocol.

A connector is an MCP server. It gives the agent tools beyond your codebase: reading an issue tracker, querying a database, calling an internal API. Connectors are for the *agent*; plugins are for the editor.

Adding one from the list

Three ways to the same list: Add connector on the Customize page of AstraCode Settings, AstraCode: MCP: Add Connector in the command palette, or Connectors in the + menu under the composer. Each entry shows the exact command it will run, or the address it will call, before anything is written. If it needs a token, such as GitHub's, you are asked for it there; it is kept in your system keychain, given only to that connector, and never written to settings. Its tools are available a few seconds later, with no restart.

Is it working?

The Customize page lists every connector, where it was named, and what it is doing, updated as it changes: starting, connected with how many tools it offers, needs sign-in, needs approval, failed with the reason, or turned off. An entry with a mistake in it is listed with what is wrong rather than left out. Connection log has the detail. The first start of a connector run with npx downloads it, which can take up to a minute or two.

Managing a connector

Each row in Customize has the actions that apply to it, and the Connectors menu under the composer has the ones waiting on you:

Changing one connector restarts that one only; the others keep running, and so do their tool calls.

GitHub

GitHub connects to GitHub's own MCP server at https://api.githubcopilot.com/mcp/, so there is nothing to install. It asks for a personal access token: create one at github.com/settings/tokens with the repo, read:org and read:packages scopes, or a fine-grained token limited to the repositories you choose. The token is kept in your system keychain and sent only to that address. If GitHub later refuses it, the connector says so; choose Set token to paste a new one. A token is given only to the entry it was stored for: an entry renamed to github, or GitHub's entry edited to call somewhere else, is not given it and says the token belongs to a different server.

A GitHub connector added before this version runs the old @modelcontextprotocol/server-github package, which GitHub no longer supports. The editor notices it in your own settings and offers, once, to Switch it to GitHub's server as github, the name it was added under; the token you gave the old one moves with it, keychain to keychain, so you are not asked again. Nothing changes unless you choose it, and a project's settings are never touched. Choosing Don't ask again leaves it alone; you can still remove it and add GitHub again.

Filesystem

Filesystem asks which folder the agent may read and write, offering the workspace root first, and shows the command with that folder before you agree. The server can reach that folder and nothing else; it can write, move and create files there. A Filesystem connector added before this version was given no folder and could reach nothing, because the server takes its folder on its command line. The editor offers, once, to Choose folder and adds it to that connector; or remove it and add it again.

Figma

Figma's online MCP server only accepts apps Figma has approved, so AstraCode connects to the Figma desktop app instead. In Figma, open Dev Mode (Shift+D) and choose Enable desktop MCP server, then add Figma (desktop app) from the list. It needs a Figma Dev or Full seat. If the app is closed or its server is off, the connector says so; open Figma, turn the server on, and choose Retry.

Adding one by hand

Anything not on the list goes in the astracode.mcp.servers setting. Each entry has an id and then either a command to run or a url to call. An entry with both, with neither, or with an id already taken is not started, and Customize lists it with the reason.

A project's own servers

A project can name servers in its workspace settings, and AstraCode also reads the MCP files other tools keep in a repository: .mcp.json (Claude Code), .cursor/mcp.json (Cursor), and the mcp.json with a servers map that some editors keep in the project's settings folder. They are read only once you trust the folder, and each server still asks once before it starts, showing exactly what it runs; the approval is for that workspace on this machine, and any change to the command, its arguments, its environment or its address asks again. Until then it is listed as needing approval, with Approve.

In those files ${env:NAME}, ${workspaceFolder} and ${userHome} are expanded, and "disabled": true is honoured. An entry that needs an editor's inputs prompts, an envFile, or the older SSE transport is listed as not supported, with what to change.

A project's servers run beside your own; they do not replace them. Where the same id is named in more than one place, the project's settings win, then its MCP files, then your own settings, and Customize shows the others as overridden. A project's servers never receive a token you stored for one of your own connectors, even under the same id. Add connector and the on/off switches change your user settings only.

Remote servers sign you in

A server reached over url uses OAuth. When it starts and has no sign-in yet, it is listed as needs sign-in and nothing opens by itself; the first time a chat would have used it, the chat says so once. Choose Sign in there, in Customize or in the Connectors menu, and a browser opens for you to approve. The token is stored for you; you are not asked to paste one.

Where the service accepts it, AstraCode identifies itself by its published client document, astracode.io/oauth/mcp-client.json, so the approval page names AstraCode and nothing is registered with the service; otherwise it registers itself as before. The browser returns to one of the local ports 45813 to 45817 when one is free. AstraCode checks that the answer came from the server it asked before using it.

Protocol versions

AstraCode speaks MCP 2026-07-28 and the 2025 versions most servers use today (2025-03-26 through 2025-11-25). It asks each server which it speaks and uses the newest both understand, so a connector needs no setting for this. A server that speaks only versions AstraCode does not is listed as not connected, with the versions it named.

While that browser sign-in is open, the editor shows a notification naming the service, with Cancel. If it is not finished within ten minutes, or it fails, the editor tells you why and offers Try again; until then that server's tools are not available to the agent.

Using them

Connector tools appear to the agent as mcp__<server>__<tool>. They always ask for approval before running, in every mode except Bypass. In Plan mode, which is read-only, a tool runs without asking only if its server declares it read-only and not destructive; anything else is asked about every time, and Approve the rest does not cover it. In a folder you have not trusted, those tools do not run at all. Switch individual connectors on and off from Connectors in the + menu under the composer, which is always there and also adds and removes them; Manage connectors opens them in Customize.

Servers your organisation offers

An admin can publish connectors for the team. These are offered, never installed silently: you see the exact command and nothing runs until you accept.

Your approval is bound to what the server actually runs, not to its name. If an admin changes the command, the arguments or the environment, it reads as a new server that has never been approved and you are asked again. Approval is per machine and is not synced.

Your own connectors never wait for these: they start first, and the organisation's are added after. Not now is remembered until the editor restarts, and Customize lists the server as needing approval, with Approve, and each approved one with a switch to turn it off on this machine. The list is checked again every fifteen minutes and when the window regains focus, so a server an admin removes stops; without a connection, the servers you approved last time still start.

A shared connector is a command line written by an admin and run on your machine. Everything above follows from taking that seriously.

When a connector changes its tools

The first time a connector starts, AstraCode records each of its tools: name, description, inputs, and its safety hints, such as read-only. If a later start lists a new tool or a changed one, those are not offered to the agent until you agree, in a prompt that shows what changed. The settings page lists every tool with the description the agent is given, and marks any that read like instructions to the agent.

Limits

A request can carry only so many tools: 128 for OpenAI's models, 200 for others. Beyond that, the tools of the connectors you used least recently are left out of that request, and Customize says which; turn off connectors you are not using to choose. Output from a connector is treated as untrusted and marked as such before the model sees it, because it arrives from software you installed but did not write. There is no open marketplace: the built-in list holds servers published by the vendor of the thing they connect to, and anything else is added by writing its entry in settings.

All documentation

Get started

Agent

Context

Workspaces

Connectors

Extending AstraCode

CLI

Reference