Docs › Troubleshooting › Connector problems

Connector problems

Fix connectors (MCP servers) that will not start, will not sign in, time out, or whose tools are missing.

On this page

Every connector shows its state in AstraCode Settings > Customize > MCP servers, with the reason when it is not working. The full story is in the AstraCode MCP log: run AstraCode: MCP: Show Connection Log, or choose Connection log on that page. Setup is on Connectors and the entry format on Connector configuration reference.

not started: the entry is invalid

The state reads not started: with one of: it has neither a command nor a url, it has both a command and a url, it is type "http" without a url, its url could not be parsed, it has no id, or a second server called the same id.

  1. Run AstraCode: MCP: Edit Servers, or choose Open config.
  2. Fix the entry in astracode.mcp.servers: an id, and exactly one of command or url, with every id different.
  3. Save. The connector starts on its own.

not started: it is plain http to a remote host

Cause: a url must be https://. Plain http:// is allowed only to localhost, 127.0.0.1 or [::1]. Change the address to https://.

The id contains __

Cause: __ separates the server from the tool in a tool's name, so an id may not contain it. Rename the id.

not supported: a project file uses inputs, envFile or the older SSE transport

Cause: a project's .mcp.json, .cursor/mcp.json or the mcp.json in its settings folder asks for something AstraCode does not do in project files.

The command was not found

The reason says the command (such as npx) was not found and that AstraCode may not see the PATH your shell sets up.

Cause: opened from the Dock, Finder or a menu, the editor does not see PATH additions made in your shell profile, such as Homebrew, nvm, asdf or ~/.local/bin.

  1. In a terminal, run command -v npx (or the command the server uses). It prints the full path.
  2. Put that full path in the entry's command.
  3. Or install what the server needs (Node.js, uv, Bun or Docker), then choose Retry.

The working directory does not exist, or permission denied

Fix the entry's cwd so it names a folder that exists, or make the command executable (chmod +x), then choose Retry.

failed: the server exited

The reason says the server exited with code a number, or wrote more than 8 MB without a newline.

  1. Open the connection log and read what the server printed before it exited.
  2. Fix its configuration or environment.
  3. Choose Retry. A server that was running and exits is retried on its own, with growing waits, for about a quarter of an hour.

A tool did not answer in time

The tool fails with a server did not answer tools/call in time (120 seconds without a reply or progress).

Cause: the tool went silent for longer than astracode.mcp.toolTimeoutSeconds, 120 seconds by default. A tool that sends progress updates keeps running.

  1. Raise astracode.mcp.toolTimeoutSeconds, up to 3600.
  2. Ask the agent to run the tool again.

needs sign-in

The chat says The connector "name" needs you to sign in before the agent can use its tools.

  1. Choose Sign in on the notice, on the connector's row in Customize, or Sign in to the connector under + > Connectors in the composer.
  2. Approve in the browser. The editor waits up to 10 minutes.

Could not sign in to a host, followed by why, offers Try again. If it keeps failing, use Sign out on the row, then Sign in again.

The server does not let AstraCode sign in

The reason says the host does not let AstraCode register to sign in, or this server needs a client id and does not offer dynamic registration, or server requires authorization.

Cause: the service accepts only apps it has approved. This cannot be fixed from the editor.

needs approval

Cause: a project's file, your organisation, or a plugin names a server that would run a program on this machine, and you have not agreed yet.

  1. Read the program it would run, shown in the prompt or on the row.
  2. Choose Run it in the prompt, or Approve on the row.
  3. For a plugin's server, approve the plugin under Customize > Plugins.

MCP: Forget Approved Organisation Servers (or Forget approvals) clears these approvals, including those for project servers in every workspace, so each asks again.

GitHub: no token, or the token was refused

The reason says no GITHUB_PERSONAL_ACCESS_TOKEN is stored, or that the server refused the GITHUB_PERSONAL_ACCESS_TOKEN stored in your keychain.

  1. Create a token at github.com/settings/tokens with the repo, read:org and read:packages scopes, or a fine-grained token for the repositories you choose.
  2. Choose Set token on the GitHub row, or Set GitHub token under + > Connectors.
  3. Paste the token. It is kept in your keychain.

The token stored for a connector belongs to a different server: choose Set token to give this connector its own, or Remove it.

Figma: the desktop app is not answering

  1. Open the Figma desktop app.
  2. Open Dev Mode (Shift+D) and choose Enable desktop MCP server.
  3. Choose Retry on the Figma row in AstraCode.

403: the server refused the request

Cause: the account you signed in with does not have access to what the tool asked for. Grant it access on the service's side, then try again.

The server redirected

Cause: the server moved to another address. Put the new address in the entry's url.

The server speaks a different protocol version

The reason says the server speaks MCP followed by versions AstraCode does not. Update the server to a current version.

The server asked for something AstraCode does not provide

Cause: the server needs a feature the editor does not offer, such as asking you a question mid-tool. There is no fix on your side; use another tool for that job.

Some connector tools were left out

Customize says the last request could carry at most a number of tools, so some connector tools were left out.

Cause: a request can carry a limited number of tools. Built-in tools always stay; connector tools are dropped, least recently used server first.

Turn off connectors you are not using, so the ones you need stay.

A tool changed and is not offered

Cause: a server changed its tools since you last agreed. Changed tools are marked (changed; not offered until you agree) and are not given to the agent.

  1. Read what the tools now tell the agent, under What its tools tell the agent on the row.
  2. Choose Offer them to the agent in the prompt.

Connector tools do not run in this folder

Cause: the folder is not trusted. A project's own servers are not started, and a connector tool that does not declare it only reads is refused. Trust the folder with Workspaces: Manage Workspace Trust. See Workspace trust.

← Agent run problems Dictation problems →

All documentation

Get started

Using the editor

Agent

Context

Workspaces

Connectors

Extending AstraCode

CLI

Account and usage

Troubleshooting

Reference