# Attach a remote MCP server

Connect an existing tool service with an explicit endpoint, tool allowlist, and operator-managed credential reference.

A remote MCP server is a service you already run or trust. A builtin server can use the Python helper described in [backend tools](/docs/raw/backend-tools?locale=en). Attach either to an agent profile or an admitted run by server ID.

The operator must permit the endpoint destination and provision any remote credential reference. Browser callers cannot register endpoints or provide private credential references. Do this from a backend key with configure scope.

### Python

```python
server = await agents.mcp_servers.create(
    name="Knowledge search",
    kind="remote",
    url="https://tools.example/mcp/",
    allowed_tools=["search_documents"],
    required=True,
    secret_ref="knowledge-service",
)
ready = await agents.mcp_servers.validate(server.id)
print(ready.status, ready.tools)

session = await agents.sessions.create(title="Research request")
run = await session.send(
    "Find the published support policy and summarize the escalation steps.",
    idempotency_key=persisted_request_id,
    mcp_server_ids=[server.id],
)
```

### TypeScript

```typescript
const server = await agents.mcpServers.create({
  name: "Knowledge search",
  kind: "remote",
  url: "https://tools.example/mcp/",
  allowed_tools: ["search_documents"],
  required: true,
  secret_ref: "knowledge-service",
})
const ready = await agents.mcpServers.validate(server.id)
console.log(ready.status, ready.tools)

const session = await agents.sessions.create({ title: "Research request" })
const run = await session.send(
  "Find the published support policy and summarize the escalation steps.",
  {
    idempotencyKey: persistedRequestId,
    mcp_server_ids: [server.id],
  },
)
```

`secret_ref` is an operator-provisioned reference, not a secret value and not an environment-variable name the user can choose freely. Omit it for a permitted service that needs no credential. The API validates destinations, redirects, and required capabilities.

## Reuse tools through a profile

### Python

```python
profile = await agents.profiles.create(
    name="Support researcher",
    instructions="Use the approved sources. Cite the document identifiers.",
    mcp_server_ids=[server.id],
    max_cost_microusd=300_000,
    timeout_seconds=120,
)
session = await agents.sessions.create(
    title="Support research",
    profile_id=profile.id,
)
```

### TypeScript

```typescript
const profile = await agents.profiles.create({
  name: "Support researcher",
  instructions: "Use the approved sources. Cite the document identifiers.",
  mcp_server_ids: [server.id],
  max_cost_microusd: 300_000,
  timeout_seconds: 120,
})
const session = await agents.sessions.create({
  title: "Support research",
  profile_id: profile.id,
})
```

The run retains its admitted tool/catalog revision. Reconfiguring a server does not silently broaden the permissions of already running work. Revoking a server prevents future use. Cancellation of already-running work remains an explicit operation.

If validation fails, inspect the returned state and safe error. Do not treat a successful TCP connection as proof that the server has the expected tools or usable authorization.
