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
- not started: the entry is invalid
- not started: it is plain http to a remote host
- The id contains __
- not supported: a project file uses inputs, envFile or the older SSE transport
- The command was not found
- The working directory does not exist, or permission denied
- failed: the server exited
- A tool did not answer in time
- needs sign-in
- The server does not let AstraCode sign in
- needs approval
- GitHub: no token, or the token was refused
- Figma: the desktop app is not answering
- 403: the server refused the request
- The server redirected
- The server speaks a different protocol version
- The server asked for something AstraCode does not provide
- Some connector tools were left out
- A tool changed and is not offered
- Connector tools do not run in this folder
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.
- Run AstraCode: MCP: Edit Servers, or choose Open config.
- Fix the entry in
astracode.mcp.servers: anid, and exactly one ofcommandorurl, with everyiddifferent. - 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.
- inputs prompts: use
${env:NAME}and set the variable instead. - envFile: put the values in
env, or in your environment. - type "sse": use the server's Streamable HTTP address (often ending
/mcp) withtypehttp. Or add the server to your ownastracode.mcp.serversby itsurl: older servers are reached there automatically.
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.
- In a terminal, run
command -v npx(or the command the server uses). It prints the full path. - Put that full path in the entry's
command. - 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.
- Open the connection log and read what the server printed before it exited.
- Fix its configuration or environment.
- 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.
- Raise
astracode.mcp.toolTimeoutSeconds, up to 3600. - 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.
- Choose Sign in on the notice, on the connector's row in Customize, or Sign in to the connector under + > Connectors in the composer.
- 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.
- Use the service's local server or an API key, if it offers one.
- For Figma, use the Figma desktop app's server, which needs no sign-in.
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.
- Read the program it would run, shown in the prompt or on the row.
- Choose Run it in the prompt, or Approve on the row.
- 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.
- Create a token at github.com/settings/tokens with the
repo,read:organdread:packagesscopes, or a fine-grained token for the repositories you choose. - Choose Set token on the GitHub row, or Set GitHub token under + > Connectors.
- 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
- Open the Figma desktop app.
- Open Dev Mode (Shift+D) and choose Enable desktop MCP server.
- 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.
- Read what the tools now tell the agent, under What its tools tell the agent on the row.
- 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
- 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