Fix a server that doesn't work
What each MCP server status means, what a mission says when a server stops it, and where to see the servers that an agent had.
Overview
An MCP server that can't be used never disappears quietly. Its card on the project's page says what is wrong, and the Vault's inventory shows the same status. If an agent of a mission should get the server, the mission stops before that agent starts. The message names the server.
Read a server's status
| Status | What it means | What to do |
|---|---|---|
| Ready | The server is reachable with its credential. | Nothing. Agents in its enabled roles get it on their next run. |
| Needs credential | The server refused a request without a credential. | Select Connect to sign in, or edit the binding to add a header. |
| Reconnect needed | The stored sign-in expired or the provider revoked it. | Select Reconnect. |
| URL changed | The repository now gives this server a different host from the host that its credential is pinned to. | If you trust the new host, edit the binding and save it for the new URL. |
| Preparing | SHIP fetches, verifies and builds the package of an isolated server. | Wait a few minutes. The page checks the status again automatically. |
| Preparing failed | SHIP could not prepare the package. The card gives the reason. | To retry, save the binding again. You can also bind the vendor's hosted endpoint. |
| Can't run isolated | The server is not an npm package, so it can't run in the isolated runtime. | Run it in the sandbox if it needs no secret, or bind its hosted endpoint. |
| Not declared | The binding remains, but the repository's MCP file no longer declares the server. | Remove the binding, or declare the server again. Until then, no agent receives it. |
From a terminal, ship mcp list shows the same statuses and ends with the command to run next for each server that isn't ready:
github ready planner 6 tools, builder 6 tools, qa 4 tools https://api.githubcopilot.com/mcp/
linear needs a credential planner no tool list yet, builder no tool list yet https://mcp.linear.app/mcp
figma needs reconnecting builder 2 tools https://mcp.figma.com/mcp
postgres not bound docker run -i --rm -e DATABASE_URL mcp/postgres
Next:
ship mcp connect figma --project prj_123
ship mcp connect linear --project prj_123
ship mcp bind postgres --roles planner,builder --url <hosted https endpoint> --project prj_123Act on a stopped mission's message
Before an agent starts, SHIP checks every server that agent should get. If one can't be used, the mission stops at that agent with a message in its activity, such as:
MCP servers for the planner agent cannot be mounted: MCP server 'linear' needs reconnecting; fix its binding on the project's page in SHIPFix the binding. Then restart the mission. The fix applies to the next agent. Nothing else in the mission changes. Two other messages name a configuration to change, not a binding:
- A harness without MCP support.
The pi harness cannot use MCP servers.Remove the role from those servers' bindings, or run the role on a harness from the supported list. - A server that ship.yml asks for, but the project doesn't grant. For example:
MCP server 'sentry' is requested for reviewer but has no binding in this project. The ship.yml file and the per-issue override can only narrow what the bindings allow. So a server that they name for a role must also have a binding for that role.
Fix an MCP file SHIP can't read
If the repository's MCP file isn't valid JSON, the project's page shows where it fails. Every binding reads MCP file invalid until you fix the file. Agents in roles with a bound server stop before they start, because SHIP can't check their servers against the file.
Fix the file on your default branch. SHIP reads it again at the start of the next mission.
See which servers an agent had
The record of each attempt lists the servers that its agent got. SHIP also records on the mission each tool call that an agent makes through SHIP, and this includes refused calls. In the timeline of a claude-code run, the first row also lists the servers that the agent started with, and whether each one connected. So the run shows a server that failed to start inside the sandbox:
If a server failed to start in the sandbox, the agent's session log usually shows the error from the server. For example, the package doesn't exist, or the server needs a secret that it didn't get.
How is this page?