---
title: "Attach or update an agent MCP server"
method: PUT
path: "/agents/{agent_id}/mcp-servers/{server_id}"
tags: ["Agents"]
---

# Attach or update an agent MCP server

`PUT /agents/{agent_id}/mcp-servers/{server_id}`

Attach an MCP server (connector) to an agent, or update its configuration if it's already attached (upsert).

The `server_id` is validated against the caller's MCP catalog. Catalog identity fields (`type`, `server_id`, `secret_id`, `mcp_server_url`) always come from the catalog and cannot be spoofed via the request body — the body carries only free-form connector configuration (e.g. approval mode, tool restrictions); any identity keys in it are ignored.

Attach may succeed before OAuth is completed; `auth_status` reflects the catalog's authentication state.

## Path parameters

- `agent_id` string, required
- `server_id` string, required

## Request body

- object — Free-form connector configuration. Identity keys are catalog-derived and ignored.

## Response `200`

The attached (or updated) MCP server.

- object
  - `agent_id` string
  - `mcp_server` object — The resulting MCP server tool config, with secrets and server URL redacted.
  - `created` boolean — `true` if the server was newly attached; `false` if an existing attachment was updated.
  - `auth_status` string, nullable — Catalog authentication status for the server (e.g. whether OAuth has been completed).

## Other responses

- `401` — Unauthorized — missing or invalid API key.
- `403` — Forbidden — the caller lacks update access to the agent, or the MCP server is restricted for the organization (`mcp_server_restricted`).
- `404` — Agent not found, or the server ID is not in the caller's catalog (`mcp_server_not_found`).
- `409` — The agent has duplicate entries for this server (`ambiguous_mcp_server`); remove them and retry.
- `500` — Internal server error.

---

[API](https://skmtc.dev/gumloop/apis/public-api.md) · [All operations](https://skmtc.dev/gumloop/apis/public-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/gumloop/public-api/revisions/115f2d6ce387/schema)