Skip to main content
PATCH
Update an MCP server

Authorizations

Authorization
string
header
required

Your Reason API key from Settings › API keys. New keys use reason_; legacy ara_ keys remain accepted. Keys are capability-scoped: run, mcp:read, mcp:write, secrets:read, secrets:write, sessions:read, sessions:debug, knowledge:read, memory:read, memory:write, skills:read, skills:write, repos:read, repos:write, reviews:read, reviews:write, deployment:read, analytics:read, org:read, org:write, attachments:read, attachments:write, guardrails:read, guardrails:write, network:read, network:write, automations:read, automations:write, agent_auth:read. network:read and network:write are opt-in, excluded from default keys. network:read reads the saved workspace network policy; network:write replaces custom allowed hosts and requires a current organization owner/admin. Legacy project PATCH requests containing network_allowed_hosts also require network:write plus their existing run scope and project management permission; saved project hosts do not affect current session egress. Only owners/admins can mint or manage keys with network:write; keys cannot grant themselves more authority. See /docs/network-policies for replacement semantics and runtime applicability. mcp:write manages MCP server configuration only; it does not authorize remote MCP-tool execution. sessions:read reads sessions, including the assistant, reasoning and tool activity in their events. sessions:debug is privileged: only for organization owners/admins, it expands session events to the full diagnostic projection (diagnostic event kinds, status text and raw event metadata).

Path Parameters

orgId
string
required

Organization id or slug. Resolve it with GET /v3/self.

id
string
required

The MCP server id, returned as id by listMcpServers.

Body

application/json

Request body for creating or updating an MCP server. On update, every property is optional and only the supplied fields change.

name
string
required
transport
enum<string>
required
Available options:
http,
stdio,
sse
icon
string
description
string
url
string
command
string
args
string[]
env
object
headers
object
auth_type
enum<string>
Available options:
none,
oauth,
bearer
secrets
object

Write-only. Secret values to store on this server, by name; the names come back as secret_names. On update, a name you omit keeps its stored value and an empty string removes it. Stored apart from workspace and personal secrets. Never returned in any response.

enabled
boolean

Response

The updated MCP server.

An org-level MCP server. Secret values are write-only and are never returned; only secret_names lists which of the server's own credentials are set.

id
string

MCP server id; pass it as id to getMcpServer.

slug
string

URL-safe identifier of the server, unique in the workspace.

name
string

Display name.

icon
string | null

Icon reference, or null when none is set.

description
string

What the server provides.

source
string

How the server was added: curated (from Reason's catalog), custom, or registry.

transport
enum<string>

How the agent reaches the server: http or sse at url, or stdio by launching command.

Available options:
http,
stdio,
sse
url
string | null

Endpoint for http and sse servers; null for stdio.

command
string | null

Executable launched for a stdio server; null otherwise.

args
string[]

Arguments passed to command.

env
object

Environment variables for a stdio server. Values can reference the server's stored credentials as $NAME; the values themselves are never returned.

headers
object

HTTP headers sent to the server. Values can reference the server's stored credentials as $NAME, such as Bearer $MCP_API_KEY.

auth_type
enum<string>

How the server authenticates: none, an OAuth connection, or a bearer credential stored on the server.

Available options:
none,
oauth,
bearer
oauth_connected
boolean

OAuth servers: whether the workspace has completed the OAuth connection.

oauth_expired
boolean

OAuth servers: whether the grant expired with no refresh token, so it needs reconnecting.

connection_state
string

Latest known connection state: unverified, ready, needs_auth, offline, protocol_error or disabled.

connection_checked_at
string | null

Timestamp of the latest recorded connection check.

connection_last_success_at
string | null

Timestamp of the last successful check, retained independently when later checks fail. Historical evidence does not imply current readiness.

connection_error_code
string | null

Public-safe code for the current connection failure.

owner_user_id
string | null

Personal installation owner, or null for a shared workspace installation. Other users' personal installations are not listed.

can_manage
boolean

Whether the caller can manage this installation through the connection lifecycle API.

tool_names
string[]

Tool names from the server's current verified configuration.

secret_names
string[]

The names of the credentials stored on this server itself, set through secrets on create or update. They belong to this server only and are not workspace or personal secrets: the secrets endpoints do not list or delete them. Secret values are write-only and are never returned.

access
string

Who can use the server; organization (the whole workspace).

enabled
boolean

Whether sessions connect to the server.

created_at
string<date-time>

When the server was added.

updated_at
string<date-time>

When the server was last changed.