Connect a hosted server

Overview

A hosted server is a server that your repository declares by URL, such as GitHub's or Linear's. Agents reach it through SHIP. SHIP attaches the credential to each request and sends the credential only to that URL. This guide binds three servers from this .mcp.json:

{
  "mcpServers": {
    "github": { "type": "http", "url": "https://api.githubcopilot.com/mcp/" },
    "linear": { "type": "http", "url": "https://mcp.linear.app/mcp" },
    "postgres": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "DATABASE_URL", "mcp/postgres"]
    }
  }
}

To bind servers, you must be an owner or admin of the organization. Members see the same pages, but without the controls. Each CLI command below takes --project <id>, or reads SHIP_PROJECT_ID.

Bind GitHub's server with a token

GitHub's MCP server takes a personal access token as a bearer header. Create a fine-grained token that has only the repositories and permissions that your agents need. Read access to issues, pull requests and code is enough to plan and verify.

Bind it for the agents that need it

ConsoleCLI

Open the project. Select Bind on the github card. Tick the agents. Add an Authorization header with the value Bearer followed by your token. Select Save binding to store the header encrypted. SHIP never shows it again.

Approve the tools agents may call

SHIP lists the server's tools when you bind it. Approve the tools that your agents need. The others stay hidden. The Reviewer and the QA agent receive only the tools that the server marks read-only, and each unannotated tool that you attest as read-only.

ship mcp tools github --approve get_issue,list_pull_requests,search_code,get_file_contents --attest get_file_contents

[x] get_issue  read-only
[x] list_pull_requests  read-only
[x] search_code  read-only
[x] get_file_contents  unannotated, attested read-only
4 of 7 approved - planner 4 tools, builder 4 tools, qa 4 tools

In the console, make the same choice in the Tools dialog on the server's card.

Refresh when the server changes

If the server adds a tool later, no agent gets it until you approve it. To see the new tool, refresh the list:

ship mcp tools github --refresh

[x] get_issue  read-only
[x] list_pull_requests  read-only
[x] search_code  read-only
[x] get_file_contents  unannotated, attested read-only
[ ] create_pull_request  writes
[ ] add_issue_comment  unannotated
[ ] merge_pull_request  writes, destructive
[ ] list_workflow_runs  read-only
4 of 8 approved - planner 4 tools, builder 4 tools, qa 4 tools

Sign in to Linear's server with OAuth

Linear's MCP server uses an OAuth sign-in, not a token. SHIP registers itself with the provider, runs the sign-in, and then renews the authorization. The agents never receive the token, and they never start a sign-in of their own.

ship mcp bind linear --roles planner,builder

Linear can later refuse the stored authorization, for example if someone revokes the app. The card then reads Reconnect needed. Each agent that should get the server stops with that reason before it starts. To sign in again, select Reconnect.

Point a Docker server at its hosted endpoint

The sandbox has no container runtime, so a server that your repository starts with docker run can't run there. Instead, bind the vendor's hosted endpoint under the same name, with a header credential:

ConsoleCLI

The Bind dialog for a Docker server offers only the hosted endpoint, and asks for its URL.

The URL must be https. SHIP pins the credential to that URL, so the repository's file can't send it to a different URL later.

Let your coding agent bind them

Your own coding agent can do all of this through the MCP server, with these tools:

• list_mcp_servers shows what the repository declares and what is bound.
• bind_mcp_server binds a server or edits its binding.
• refresh_mcp_server_tools lists the tools of a server.
• start_mcp_server_oauth returns the sign-in link for you to open.

The tools take the same fields as the API.