---
title: "Bind a declared MCP server: roles, approved tools and credential"
method: PUT
path: "/mcp/projects/{projectId}/servers/{serverName}"
tags: ["mcp"]
---

# Bind a declared MCP server: roles, approved tools and credential

`PUT /mcp/projects/{projectId}/servers/{serverName}`

## Request

- Base URL: `https://api.letsship.ai/v1`
- URL: `https://api.letsship.ai/v1/mcp/projects/{projectId}/servers/{serverName}`
- Auth: none declared

## Path parameters

- `projectId` string, required
- `serverName` string, required

## Request body

- UpsertMcpBindingRequest
  - `roles` McpRole[], required
  - `transport` 'remote' | 'isolate' | 'local': 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).
  - `remoteUrl` string, uri
  - `credential` union
    - object
      - `kind` 'none', required
    - object
      - `kind` 'headers', required
      - `headers` object, required
    - object
      - `kind` 'isolate-env', required
      - `env` object, required
      - `allowedHosts` string[], required
  - `approvedTools` McpApprovedTool[]
    - `name` string, required
    - `attestedReadOnly` boolean

## Response `200`

Binding

- McpBinding
  - `transport` 'remote' | 'isolate' | 'local', required: 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).
  - `status` 'ready' | 'needs_credential' | 'needs_reconnect' | 'origin_changed' | 'bundling' | 'bundle_failed' | 'not_isolatable', required
  - `statusDetail` string, nullable, required
  - `roles` McpRole[], required
  - `authKind` 'none' | 'headers' | 'oauth' | 'isolate-env', required
  - `pinnedUrl` string, nullable, required
  - `packageSpec` string, nullable, required
  - `allowedEgressHosts` string[], required
  - `credentialFields` string[], required
  - `toolSnapshot` McpToolSnapshotEntry[], required
    - `name` string, required
    - `title` string
    - `description` string
    - `readOnlyHint` boolean
    - `destructiveHint` boolean
  - `approvedTools` McpApprovedTool[], required
    - `name` string, required
    - `attestedReadOnly` boolean
  - `toolsRefreshedAt` integer, nullable, required
  - `effectiveToolCounts` object, required
    - `planner` integer, nullable
    - `builder` integer, nullable
    - `reviewer` integer, nullable
    - `qa` integer, nullable
  - `createdAt` integer, required
  - `updatedAt` integer, required

## Other responses

- `400`: Invalid
- `403`: Role insufficient
- `404`: Not found (also for other tenants)

---

[API](https://skmtc.dev/letsship/apis/ship-api.md) · [All operations](https://skmtc.dev/letsship/apis/ship-api/llms.txt) · [OpenAPI document](https://skmtc.dev/letsship/apis/ship-api/revisions/e6eac1bcadd4?raw)