API

MCP

Bind each MCP server that your repository declares: the agents that may use it, its approved tools and its credential.

GET
/mcp/projects/{projectId}

Path Parameters

projectId*string
Length1 <= length

Response Body

Project MCP view

application/json
  1. response
projectId*string
configPath*string
configPathSource*McpConfigPathSource

Which layer named the MCP file: the repository's ship.yml (mcp.config), the path set on the project, or the default .mcp.json. ship.yml wins.

Value in"ship.yml""project""default"
configRef*string|null
configStatus*string
Value in"ok""missing""invalid""unreadable"
configError*string|null
warnings*array<string>
servers*array<>
Example Request
curl -X GET 'https://api.letsship.ai/v1/mcp/projects/string'
Example Response
{  "projectId": "string",  "configPath": "string",  "configPathSource": "ship.yml",  "configRef": "string",  "configStatus": "ok",  "configError": "string",  "warnings": [    "string"  ],  "servers": [    {      "name": "string",      "declared": {        "name": "string",        "transport": "http",        "origin": "string",        "path": "string",        "command": "string",        "displayArgs": [          "string"        ],        "headerNames": [          "string"        ],        "envNames": [          "string"        ],        "secretRefs": [          "string"        ],        "isolation": {          "kind": "remote",          "packageSpec": "string",          "reason": "python"        }      },      "binding": {        "transport": "remote",        "status": "ready",        "statusDetail": "string",        "roles": [          "planner"        ],        "authKind": "none",        "pinnedUrl": "string",        "packageSpec": "string",        "allowedEgressHosts": [          "string"        ],        "credentialFields": [          "string"        ],        "toolSnapshot": [          {            "name": "string",            "title": "string",            "description": "string",            "readOnlyHint": true,            "destructiveHint": true          }        ],        "approvedTools": [          {            "name": "string",            "attestedReadOnly": true          }        ],        "toolsRefreshedAt": 0,        "effectiveToolCounts": {          "planner": 0,          "builder": 0,          "reviewer": 0,          "qa": 0        },        "createdAt": 0,        "updatedAt": 0      }    }  ]}
PATCH
/mcp/projects/{projectId}

Path Parameters

projectId*string
Length1 <= length

Request Body

application/json
  1. body
configPath*|
Match^[^/][^\0]*$
Length1 <= length <= 256

Response Body

Updated view

application/json
  1. response
projectId*string
configPath*string
configPathSource*McpConfigPathSource

Which layer named the MCP file: the repository's ship.yml (mcp.config), the path set on the project, or the default .mcp.json. ship.yml wins.

Value in"ship.yml""project""default"
configRef*string|null
configStatus*string
Value in"ok""missing""invalid""unreadable"
configError*string|null
warnings*array<string>
servers*array<>
Example Request
curl -X PATCH 'https://api.letsship.ai/v1/mcp/projects/string' \  -H 'Content-Type: application/json' \  -d '{  "configPath": "string"}'
Example Response
{  "projectId": "string",  "configPath": "string",  "configPathSource": "ship.yml",  "configRef": "string",  "configStatus": "ok",  "configError": "string",  "warnings": [    "string"  ],  "servers": [    {      "name": "string",      "declared": {        "name": "string",        "transport": "http",        "origin": "string",        "path": "string",        "command": "string",        "displayArgs": [          "string"        ],        "headerNames": [          "string"        ],        "envNames": [          "string"        ],        "secretRefs": [          "string"        ],        "isolation": {          "kind": "remote",          "packageSpec": "string",          "reason": "python"        }      },      "binding": {        "transport": "remote",        "status": "ready",        "statusDetail": "string",        "roles": [          "planner"        ],        "authKind": "none",        "pinnedUrl": "string",        "packageSpec": "string",        "allowedEgressHosts": [          "string"        ],        "credentialFields": [          "string"        ],        "toolSnapshot": [          {            "name": "string",            "title": "string",            "description": "string",            "readOnlyHint": true,            "destructiveHint": true          }        ],        "approvedTools": [          {            "name": "string",            "attestedReadOnly": true          }        ],        "toolsRefreshedAt": 0,        "effectiveToolCounts": {          "planner": 0,          "builder": 0,          "reviewer": 0,          "qa": 0        },        "createdAt": 0,        "updatedAt": 0      }    }  ]}
DELETE
/mcp/projects/{projectId}/servers/{serverName}

Path Parameters

projectId*string
Length1 <= length
serverName*string
Match^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$

Response Body

Deleted

application/json
  1. response
deleted*true
Value intrue
Example Request
curl -X DELETE 'https://api.letsship.ai/v1/mcp/projects/string/servers/string'
Example Response
{  "deleted": true}
PUT
/mcp/projects/{projectId}/servers/{serverName}

Path Parameters

projectId*string
Length1 <= length
serverName*string
Match^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$

Request Body

application/json
  1. body
roles*array<>
Itemsitems <= 4
transport?McpBindingTransport

remote: the gateway proxies to the server's URL. isolate: the gateway runs the server's npm package in an isolated runtime. local: the server runs inside the agent's sandbox (no credential).

Value in"remote""isolate""local"
remoteUrl?string
Formaturi
Lengthlength <= 2048
credential?||
approvedTools?array<>
Itemsitems <= 200

Response Body

Binding

application/json
  1. response
transport*McpBindingTransport

remote: the gateway proxies to the server's URL. isolate: the gateway runs the server's npm package in an isolated runtime. local: the server runs inside the agent's sandbox (no credential).

Value in"remote""isolate""local"
status*McpBindingStatus
Value in"ready""needs_credential""needs_reconnect""origin_changed""bundling""bundle_failed""not_isolatable"
statusDetail*string|null
roles*array<>
authKind*McpAuthKind
Value in"none""headers""oauth""isolate-env"
pinnedUrl*string|null
packageSpec*string|null
allowedEgressHosts*array<string>
credentialFields*array<string>
toolSnapshot*array<>
approvedTools*array<>
toolsRefreshedAt*integer|null
effectiveToolCounts*
createdAt*integer
updatedAt*integer
Example Request
curl -X PUT 'https://api.letsship.ai/v1/mcp/projects/string/servers/string' \  -H 'Content-Type: application/json' \  -d '{  "roles": [    "planner"  ]}'
Example Response
{  "transport": "remote",  "status": "ready",  "statusDetail": "string",  "roles": [    "planner"  ],  "authKind": "none",  "pinnedUrl": "string",  "packageSpec": "string",  "allowedEgressHosts": [    "string"  ],  "credentialFields": [    "string"  ],  "toolSnapshot": [    {      "name": "string",      "title": "string",      "description": "string",      "readOnlyHint": true,      "destructiveHint": true    }  ],  "approvedTools": [    {      "name": "string",      "attestedReadOnly": true    }  ],  "toolsRefreshedAt": 0,  "effectiveToolCounts": {    "planner": 0,    "builder": 0,    "reviewer": 0,    "qa": 0  },  "createdAt": 0,  "updatedAt": 0}
POST
/mcp/projects/{projectId}/servers/{serverName}/tools/refresh

Path Parameters

projectId*string
Length1 <= length
serverName*string
Match^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$

Response Body

Binding with a fresh snapshot

application/json
  1. response
transport*McpBindingTransport

remote: the gateway proxies to the server's URL. isolate: the gateway runs the server's npm package in an isolated runtime. local: the server runs inside the agent's sandbox (no credential).

Value in"remote""isolate""local"
status*McpBindingStatus
Value in"ready""needs_credential""needs_reconnect""origin_changed""bundling""bundle_failed""not_isolatable"
statusDetail*string|null
roles*array<>
authKind*McpAuthKind
Value in"none""headers""oauth""isolate-env"
pinnedUrl*string|null
packageSpec*string|null
allowedEgressHosts*array<string>
credentialFields*array<string>
toolSnapshot*array<>
approvedTools*array<>
toolsRefreshedAt*integer|null
effectiveToolCounts*
createdAt*integer
updatedAt*integer
Example Request
curl -X POST 'https://api.letsship.ai/v1/mcp/projects/string/servers/string/tools/refresh'
Example Response
{  "transport": "remote",  "status": "ready",  "statusDetail": "string",  "roles": [    "planner"  ],  "authKind": "none",  "pinnedUrl": "string",  "packageSpec": "string",  "allowedEgressHosts": [    "string"  ],  "credentialFields": [    "string"  ],  "toolSnapshot": [    {      "name": "string",      "title": "string",      "description": "string",      "readOnlyHint": true,      "destructiveHint": true    }  ],  "approvedTools": [    {      "name": "string",      "attestedReadOnly": true    }  ],  "toolsRefreshedAt": 0,  "effectiveToolCounts": {    "planner": 0,    "builder": 0,    "reviewer": 0,    "qa": 0  },  "createdAt": 0,  "updatedAt": 0}
GET
/mcp/bindings

Response Body

Bindings

application/json
  1. response
bindings*array<>
Example Request
curl -X GET 'https://api.letsship.ai/v1/mcp/bindings'
Example Response
{  "bindings": [    {      "projectId": "string",      "projectName": "string",      "serverName": "string",      "transport": "remote",      "status": "ready",      "statusDetail": "string",      "roles": [        "planner"      ],      "authKind": "none",      "credentialFields": [        "string"      ],      "updatedAt": 0    }  ]}
POST
/mcp/projects/{projectId}/servers/{serverName}/oauth/start

Path Parameters

projectId*string
Length1 <= length
serverName*string
Match^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$

Request Body

application/json
  1. body
scope?string
Lengthlength <= 512
returnTo?string
Match^\/
Lengthlength <= 512

Response Body

Consent URL

application/json
  1. response
authorizeUrl*string
expiresAt*integer
Example Request
curl -X POST 'https://api.letsship.ai/v1/mcp/projects/string/servers/string/oauth/start' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "authorizeUrl": "string",  "expiresAt": 0}
POST
/mcp/oauth/complete

Request Body

application/json
  1. body
code*string
Length1 <= length <= 2048
state*string
Length16 <= length <= 256

Response Body

Credential stored

application/json
  1. response
projectId*string
serverName*string
returnTo*string|null
Example Request
curl -X POST 'https://api.letsship.ai/v1/mcp/oauth/complete' \  -H 'Content-Type: application/json' \  -d '{  "code": "string",  "state": "stringstringstri"}'
Example Response
{  "projectId": "string",  "serverName": "string",  "returnTo": "string"}

How is this page?