Agent: MCP Servers

These endpoints manage the agent’s Model Context Protocol (MCP) server pool: inspect the effective merged configuration together with live connection state, add or update entries, toggle their enabled flag, remove them, import a config from another tool, preview what an import would write, and reconcile the running pool after a settings change.

Every write that touches a settings file requires a single-use nonce minted by beginMCPWrite for the specific write op and settings layer, plus the expect_hash you last read. Present another writer’s hash and the call returns 409 mcp_conflict instead of overwriting a concurrent edit. A first write into a settings file that does not exist yet passes the empty-array hash that listMCPServers and beginMCPWrite return for a missing file; an empty expect_hash is refused, so always carry the value forward.

List configured servers

`GET /api/v1/agent/mcp/servers`

Returns the EFFECTIVE merged mcp_servers config for a live session, the per-layer settings files behind it, and the LIVE runtime state of each server (connected flag, negotiated protocol revision, tool count, pid, revocation reason, recent stderr tail). Credential values are never returned; env and headers are reported as key NAMES only, because a redacted placeholder invites a client to write the placeholder back as the real secret. Each file entry carries the content hash to pass as expect_hash on a write.

Parameters

Name	In	Type	Required	Description
`session_id`	query	string	Yes	Live session id. `foldHookSession` reads this from the query string, so it is the route’s most important parameter even though the agent’s broader header set is listed below.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope: the `.hoody` project layer / record cwd / tool+workflow cwd. Required by routes that resolve a cwd.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override selecting which on-disk `.hoody` install a stateless read/write resolves.
`X-Hoody-Container`	header	string	No	Per-request bound remote container (omitted = local). Rejected (400) on routes with no container dimension.
`X-Hoody-Realm`	header	string	No	Per-request realm selector: `global` or a 24-hex id (also accepted as `?realm=`). Rejected (400 `realm_scope_unsupported`) on active-only / no-realm routes.
`realm`	query	string	No	Per-request realm selector — the in-query alias of the `X-Hoody-Realm` header (read only when the header is absent).

Responses

{
  "status": "ok",
  "servers": [
    {
      "name": "filesystem",
      "transport": "stdio",
      "require_confirmation": false,
      "enabled": true,
      "connected": true,
      "protocol_version": "2025-03-26",
      "server_name": "filesystem",
      "server_version": "0.5.0",
      "tool_count": 8,
      "pid": 48211,
      "env_keys": ["PATH"],
      "header_keys": []
    },
    {
      "name": "remote-tools",
      "transport": "http",
      "require_confirmation": false,
      "enabled": false,
      "connected": false,
      "env_keys": [],
      "header_keys": ["Authorization"]
    }
  ],
  "files": [
    {
      "path": "/home/me/.hoody/settings.json",
      "hash": "sha256:9b1f0c…",
      "layer": "user"
    },
    {
      "path": "/home/me/proj/.hoody/settings.json",
      "hash": "sha256:2a73ee…",
      "layer": "project"
    }
  ],
  "warnings": []
}

{
  "code": "bad_request",
  "message": "invalid request"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to an active-only / global-no-realm RPC, which has no realm dimension to scope.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through `hoody-proxy` (for example `hoody agent …` → platform → proxy), not by connecting to the container directly.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded; the gateway throttled the request before dispatch.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request (too busy, or a per-client stream concurrency cap was hit).	Honor `Retry-After` and retry.

SDK usage

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.agent.mcp.listMCPServers({ session_id: 'sess_01HZX9…' });

Begin a write

`POST /api/v1/agent/mcp/write-intents`

Mints the single-use nonce every MCP write requires and returns the target settings path plus its current mcp_servers hash. The nonce binds {session, op, resolved path}: a write presenting a nonce minted for a different op or scope fails closed. Pass the returned hash back as expect_hash so a concurrent edit is reported as a conflict rather than silently overwritten.

Parameters

Name	In	Type	Required	Description
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container.
`X-Hoody-Realm`	header	string	No	Per-request realm selector.
`realm`	query	string	No	In-query alias of `X-Hoody-Realm`.

Request Body

Field	Type	Required	Description
`session_id`	string	Yes	Live session id (MCP config is resolved against the session’s settings layers).
`op`	string	Yes	Which write the nonce authorizes. One of `upsert`, `delete`, `set_enabled`, `import`. The minted nonce is valid for this op alone.
`scope`	string	No	Settings layer to write. One of `user`, `project`, `local`. Defaults to `user`, or `project` when there is no user layer (the case under `--config-dir`).

{
  "session_id": "sess_01HZX9ABCDEF",
  "op": "upsert",
  "scope": "user"
}

Responses

{
  "status": "ok",
  "nonce": "nonce_01HZX9…",
  "path": "/home/me/.hoody/settings.json",
  "hash": "sha256:9b1f0c…"
}

{
  "code": "bad_request",
  "message": "invalid request"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to an active-only / global-no-realm RPC.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through `hoody-proxy`, not by connecting to the container directly.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "payload_too_large",
  "message": "request body exceeds the configured size limit"
}

Error Code	Title	Description	Resolution
`payload_too_large`	Payload too large	The request body exceeds the configured size cap (`MaxBodyBytes`). The gateway rejects an oversized body at the edge (`http.MaxBytesReader`) before the handler reads it.	Reduce the request body below the configured limit (default 8 MiB); split a large payload into smaller requests.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded.	Honor the `Retry-After` header and retry.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor `Retry-After` and retry.

SDK usage

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.agent.mcp.beginMCPWrite({
  session_id: 'sess_01HZX9ABCDEF',
  op: 'upsert',
  scope: 'user'
});

Create or update a server

`PUT /api/v1/agent/mcp/servers`

Writes one mcp_servers entry, merging FIELD BY FIELD over any existing entry of the same name so fields you omit keep their stored value — including fields this build does not model. Requires the begin-write nonce for op:upsert and an expect_hash. A body carrying the redaction placeholder for a credential is REFUSED rather than stored.

On success a re-pointed server is REVOKED in every live session before the response, and the new config is APPLIED to the session you named before the response — its reconnect is AWAITED rather than merely started, so nothing is still pending when this returns. Awaited is NOT succeeded: a server that fails to start or handshake still returns 200, so read servers[].connected in this reply before calling its tools. A session that is MID-TURN keeps the tool set it was shown and picks the new one up at the next turn boundary. Other live sessions reconnect in the BACKGROUND, so this never waits out an unrelated session’s slow server; that background pass is best-effort and is skipped under sustained pressure, in which case those sessions pick the change up on the next write or an explicit reconnect. Revocation is never best-effort.

Parameters

Name	In	Type	Required	Description
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container.
`X-Hoody-Realm`	header	string	No	Per-request realm selector.
`realm`	query	string	No	In-query alias of `X-Hoody-Realm`.

Request Body

Field	Type	Required	Description
`session_id`	string	Yes	Live session id.
`nonce`	string	Yes	Single-use nonce from `beginMCPWrite` minted for `op:upsert` and this scope; the RPC fails closed without it.
`scope`	string	No	Settings layer to write. One of `user`, `project`, `local`. Must match the scope the nonce was minted for.
`expect_hash`	string	Yes	The `mcp_servers` hash you last read, as returned by `beginMCPWrite` or `listMCPServers`. A mismatch returns 409 `mcp_conflict` instead of overwriting a concurrent edit. A first write into a file that does not exist yet states its expectation with the empty-array hash rather than omitting this.
`server`	object	Yes	The server entry. See field notes below.

The server object supports:

name — letters, digits, _ and -, max 64 chars, no __ (it separates the tool name), may not be hoody or mcp (both are reserved namespaces). The check is case-insensitive, so Hoody is also refused.
type — stdio (default), http (aliases url, streamable, streamable-http) for Streamable HTTP, or sse for the deprecated 2024-11-05 HTTP+SSE transport. Matched case-insensitively.
command + args for stdio, or url for the remote transports.
env / headers — values support full ${VAR} expansion, so a token lives in your environment rather than in settings.json.
allowed_tools — restrict which of the server’s tools are advertised AND dispatchable.
require_confirmation — park every call from this server for human approval.
enabled — defaults to true. A disabled server keeps its config but is neither connected nor advertised.

{
  "session_id": "sess_01HZX9ABCDEF",
  "nonce": "nonce_01HZX9…",
  "scope": "user",
  "expect_hash": "sha256:9b1f0c…",
  "server": {
    "name": "filesystem",
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/me/projects"],
    "env": {
      "LOG_LEVEL": "warn"
    }
  }
}

Responses

{
  "status": "ok",
  "sessions": 3,
  "revoked": 1,
  "deferred_sessions": 2,
  "deferred_started": true,
  "servers": [
    {
      "name": "filesystem",
      "transport": "stdio",
      "require_confirmation": false,
      "enabled": true,
      "connected": true,
      "protocol_version": "2025-03-26",
      "server_name": "filesystem",
      "server_version": "0.5.0",
      "tool_count": 8,
      "pid": 48211,
      "env_keys": ["LOG_LEVEL", "PATH"],
      "header_keys": []
    }
  ],
  "path": "/home/me/.hoody/settings.json",
  "hash": "sha256:7c4a1e…"
}

{
  "code": "bad_request",
  "message": "invalid request"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to an active-only / global-no-realm RPC.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through `hoody-proxy`, not by connecting to the container directly.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "mcp_conflict",
  "message": "the MCP server list changed since you read it; refresh and try again"
}

Error Code	Title	Description	Resolution
`mcp_conflict`	MCP server list conflict	The `mcp_servers` content changed between the hash you read and this write. Another writer — a second client, the TUI, or a hand edit — got there first.	Re-read the current hash (`listMCPServers`, or `beginMCPWrite` which returns it with the nonce), re-apply your change on top of what is there now, and re-issue the write.

{
  "code": "payload_too_large",
  "message": "request body exceeds the configured size limit"
}

Error Code	Title	Description	Resolution
`payload_too_large`	Payload too large	The request body exceeds the configured size cap (`MaxBodyBytes`).	Reduce the request body below the configured limit (default 8 MiB); split a large payload into smaller requests.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded.	Honor the `Retry-After` header and retry.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor `Retry-After` and retry.

SDK usage

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.agent.mcp.upsertMCPServer({
  session_id: 'sess_01HZX9ABCDEF',
  nonce: 'nonce_01HZX9…',
  scope: 'user',
  expect_hash: 'sha256:9b1f0c…',
  server: {
    name: 'filesystem',
    type: 'stdio',
    command: 'npx',
    args: ['-y', '@modelcontextprotocol/server-filesystem', '/home/me/projects']
  }
});

Delete a server

`DELETE /api/v1/agent/mcp/servers`

Removes one mcp_servers entry from the named settings layer. Requires the begin-write nonce for op:delete and an expect_hash. The server is REVOKED in every live session before the response returns, so a caller mid-turn cannot still reach it; a stdio child is reaped when its last holder releases.

Parameters

Name	In	Type	Required	Description
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container.
`X-Hoody-Realm`	header	string	No	Per-request realm selector.
`realm`	query	string	No	In-query alias of `X-Hoody-Realm`.

Request Body

Field	Type	Required	Description
`session_id`	string	Yes	Live session id.
`nonce`	string	Yes	Single-use nonce from `beginMCPWrite` minted for `op:delete` and this scope.
`scope`	string	No	Settings layer to write. One of `user`, `project`, `local`. Must match the scope the nonce was minted for.
`name`	string	Yes	The server name to remove.
`expect_hash`	string	Yes	The `mcp_servers` hash you last read. A mismatch returns 409 `mcp_conflict`.

{
  "session_id": "sess_01HZX9ABCDEF",
  "nonce": "nonce_01HZX9…",
  "scope": "user",
  "name": "filesystem",
  "expect_hash": "sha256:7c4a1e…"
}

Responses

{
  "status": "ok",
  "sessions": 3,
  "revoked": 1,
  "deferred_sessions": 2,
  "deferred_started": true,
  "servers": [],
  "path": "/home/me/.hoody/settings.json",
  "hash": "sha256:2a73ee…"
}

{
  "code": "bad_request",
  "message": "invalid request"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to an active-only / global-no-realm RPC.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through `hoody-proxy`, not by connecting to the container directly.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "mcp_conflict",
  "message": "the MCP server list changed since you read it; refresh and try again"
}

Error Code	Title	Description	Resolution
`mcp_conflict`	MCP server list conflict	The `mcp_servers` content changed between the hash you read and this write.	Re-read the current hash, re-apply your change on top of what is there now, and re-issue the write.

{
  "code": "payload_too_large",
  "message": "request body exceeds the configured size limit"
}

Error Code	Title	Description	Resolution
`payload_too_large`	Payload too large	The request body exceeds the configured size cap (`MaxBodyBytes`).	Reduce the request body below the configured limit (default 8 MiB).

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded.	Honor the `Retry-After` header and retry.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor `Retry-After` and retry.

SDK usage

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.agent.mcp.deleteMCPServer({
  session_id: 'sess_01HZX9ABCDEF',
  nonce: 'nonce_01HZX9…',
  scope: 'user',
  name: 'filesystem',
  expect_hash: 'sha256:7c4a1e…'
});

Enable or disable a server

`POST /api/v1/agent/mcp/servers/enable`

Flips one entry’s enabled flag without touching the rest of its config, so credentials and options survive a disable. Requires the begin-write nonce for op:set_enabled and an expect_hash. Disabling revokes the server in live sessions immediately.

Parameters

Name	In	Type	Required	Description
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container.
`X-Hoody-Realm`	header	string	No	Per-request realm selector.
`realm`	query	string	No	In-query alias of `X-Hoody-Realm`.

Request Body

Field	Type	Required	Description
`session_id`	string	Yes	Live session id.
`nonce`	string	Yes	Single-use nonce from `beginMCPWrite` minted for `op:set_enabled` and this scope.
`scope`	string	No	Settings layer to write. One of `user`, `project`, `local`. Must match the scope the nonce was minted for.
`name`	string	Yes	The server name.
`enabled`	boolean	Yes	`true` to enable, `false` to disable.
`expect_hash`	string	Yes	The `mcp_servers` hash you last read. A mismatch returns 409 `mcp_conflict`.

{
  "session_id": "sess_01HZX9ABCDEF",
  "nonce": "nonce_01HZX9…",
  "scope": "user",
  "name": "filesystem",
  "enabled": false,
  "expect_hash": "sha256:9b1f0c…"
}

Responses

{
  "status": "ok",
  "sessions": 3,
  "revoked": 1,
  "deferred_sessions": 2,
  "deferred_started": true,
  "servers": [
    {
      "name": "filesystem",
      "transport": "stdio",
      "require_confirmation": false,
      "enabled": false,
      "connected": false,
      "env_keys": ["LOG_LEVEL"],
      "header_keys": []
    }
  ],
  "path": "/home/me/.hoody/settings.json",
  "hash": "sha256:5d8b12…"
}

{
  "code": "bad_request",
  "message": "invalid request"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to an active-only / global-no-realm RPC.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through `hoody-proxy`, not by connecting to the container directly.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "mcp_conflict",
  "message": "the MCP server list changed since you read it; refresh and try again"
}

Error Code	Title	Description	Resolution
`mcp_conflict`	MCP server list conflict	The `mcp_servers` content changed between the hash you read and this write.	Re-read the current hash, re-apply your change on top of what is there now, and re-issue the write.

{
  "code": "payload_too_large",
  "message": "request body exceeds the configured size limit"
}

Error Code	Title	Description	Resolution
`payload_too_large`	Payload too large	The request body exceeds the configured size cap (`MaxBodyBytes`).	Reduce the request body below the configured limit (default 8 MiB).

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded.	Honor the `Retry-After` header and retry.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor `Retry-After` and retry.

SDK usage

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.agent.mcp.setMCPServerEnabled({
  session_id: 'sess_01HZX9ABCDEF',
  nonce: 'nonce_01HZX9…',
  scope: 'user',
  name: 'filesystem',
  enabled: false,
  expect_hash: 'sha256:9b1f0c…'
});

Import from another tool

`POST /api/v1/agent/mcp/import`

Imports a batch of servers from a pasted config document or an explicit array. Understands the hoody (mcp_servers list), Claude/Cursor (mcpServers map), and VS Code (servers map) dialects; a document carrying more than one of them is REFUSED rather than guessed at. Validation is WHOLE-BATCH — one bad entry aborts everything, because a partial import leaves a config the operator did not author. Imported servers land DISABLED for review; enable them with setMCPServerEnabled. Requires the begin-write nonce for op:import and an expect_hash.

Parameters

Name	In	Type	Required	Description
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container.
`X-Hoody-Realm`	header	string	No	Per-request realm selector.
`realm`	query	string	No	In-query alias of `X-Hoody-Realm`.

Request Body

Field	Type	Required	Description
`session_id`	string	Yes	Live session id.
`nonce`	string	Yes	Single-use nonce from `beginMCPWrite` minted for `op:import` and this scope.
`scope`	string	No	Settings layer to write. One of `user`, `project`, `local`. Must match the scope the nonce was minted for.
`document`	string	No	A pasted config document in any supported dialect. Mutually exclusive with the `servers` field. This is the ONLY import form the CLI exposes; the `servers` field has no CLI flag. The hoody dialect is accepted here, so anything expressible via `servers` can be passed as a document.
`servers`	array	No	Explicit server entries, in hoody’s own shape. Mutually exclusive with `document`. API/SDK only.
`replace`	boolean	No	Overwrite entries whose name already exists. Without it, a collision aborts the whole import.
`expect_hash`	string	Yes	The `mcp_servers` hash you last read. A mismatch returns 409 `mcp_conflict`.

{
  "session_id": "sess_01HZX9ABCDEF",
  "nonce": "nonce_01HZX9…",
  "scope": "user",
  "document": "{\"mcpServers\": {\"filesystem\": {\"command\": \"npx\", \"args\": [\"-y\", \"@modelcontextprotocol/server-filesystem\", \"/home/me/projects\"]}}}",
  "expect_hash": "sha256:9b1f0c…"
}

Responses

{
  "status": "ok",
  "sessions": 3,
  "revoked": 0,
  "deferred_sessions": 2,
  "deferred_started": true,
  "servers": [
    {
      "name": "filesystem",
      "transport": "stdio",
      "require_confirmation": false,
      "enabled": false,
      "connected": false,
      "env_keys": ["PATH"],
      "header_keys": []
    }
  ],
  "path": "/home/me/.hoody/settings.json",
  "hash": "sha256:5d8b12…",
  "imported": 1
}

{
  "code": "bad_request",
  "message": "invalid request"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to an active-only / global-no-realm RPC.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through `hoody-proxy`, not by connecting to the container directly.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "mcp_conflict",
  "message": "the MCP server list changed since you read it; refresh and try again"
}

Error Code	Title	Description	Resolution
`mcp_conflict`	MCP server list conflict	The `mcp_servers` content changed between the hash you read and this write.	Re-read the current hash, re-apply your change on top of what is there now, and re-issue the write.

{
  "code": "payload_too_large",
  "message": "request body exceeds the configured size limit"
}

Error Code	Title	Description	Resolution
`payload_too_large`	Payload too large	The request body exceeds the configured size cap (`MaxBodyBytes`).	Reduce the request body below the configured limit (default 8 MiB).

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded.	Honor the `Retry-After` header and retry.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor `Retry-After` and retry.

SDK usage

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.agent.mcp.importMCPServers({
  session_id: 'sess_01HZX9ABCDEF',
  nonce: 'nonce_01HZX9…',
  scope: 'user',
  document: '{"mcpServers":{"filesystem":{"command":"npx","args":["-y","@modelcontextprotocol/server-filesystem","/home/me/projects"]}}}',
  expect_hash: 'sha256:9b1f0c…'
});

Preview an import

`POST /api/v1/agent/mcp/parse`

Parses a pasted config document into the entries an import WOULD write, without touching any file. Credential values are stripped from the preview. Use it to show a user what they are about to import; it needs no nonce because it writes nothing.

Parameters

Name	In	Type	Required	Description
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container.
`X-Hoody-Realm`	header	string	No	Per-request realm selector.
`realm`	query	string	No	In-query alias of `X-Hoody-Realm`.

Request Body

Field	Type	Required	Description
`session_id`	string	Yes	Live session id.
`document`	string	Yes	A config document in any supported dialect.

{
  "session_id": "sess_01HZX9ABCDEF",
  "document": "{\"mcpServers\": {\"filesystem\": {\"command\": \"npx\", \"args\": [\"-y\", \"@modelcontextprotocol/server-filesystem\", \"/home/me/projects\"]}}}"
}

Responses

{
  "status": "ok",
  "dialect": "claude",
  "servers": [
    {
      "name": "filesystem",
      "transport": "stdio",
      "require_confirmation": false,
      "enabled": false,
      "env_keys": ["PATH"],
      "header_keys": []
    }
  ],
  "count": 1
}

{
  "code": "bad_request",
  "message": "invalid request"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to an active-only / global-no-realm RPC.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through `hoody-proxy`, not by connecting to the container directly.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "payload_too_large",
  "message": "request body exceeds the configured size limit"
}

Error Code	Title	Description	Resolution
`payload_too_large`	Payload too large	The request body exceeds the configured size cap (`MaxBodyBytes`).	Reduce the request body below the configured limit (default 8 MiB).

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded.	Honor the `Retry-After` header and retry.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor `Retry-After` and retry.

SDK usage

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.agent.mcp.parseMCPImport({
  session_id: 'sess_01HZX9ABCDEF',
  document: '{"mcpServers":{"filesystem":{"command":"npx","args":["-y","@modelcontextprotocol/server-filesystem","/home/me/projects"]}}}'
});

Probe a server

`POST /api/v1/agent/mcp/probe`

Connects to a candidate server config and reports the tools it advertises and the protocol revision it negotiated, then tears the connection down. Nothing is written. The deny list is enforced on the candidate config before anything is started.

Parameters

Name	In	Type	Required	Description
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container.
`X-Hoody-Realm`	header	string	No	Per-request realm selector.
`realm`	query	string	No	In-query alias of `X-Hoody-Realm`.

Request Body

Field	Type	Required	Description
`session_id`	string	Yes	Live session id (supplies the deny list and transport policy).
`server`	object	Yes	The candidate entry, same shape as `upsertMCPServer`’s `server`.

{
  "session_id": "sess_01HZX9ABCDEF",
  "server": {
    "name": "filesystem",
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/me/projects"]
  }
}

Responses

{
  "code": "bad_request",
  "message": "invalid request"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to an active-only / global-no-realm RPC.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "human_only",
  "message": "probing an MCP server requires direct human confirmation and is not available to machine callers"
}

Error Code	Title	Description	Resolution
`human_only`	Probing requires a human	Probing STARTS A PROCESS (stdio) or makes an outbound request to a caller-chosen URL, so an autonomous caller may not self-approve it. The gateway stamps the machine marker on every call it forwards, so there is NO successful HTTP probe path — this refusal is not a transient condition to retry.	Do not probe over HTTP; get the same information from the write itself. Create the entry with `upsertMCPServer`, then read `listMCPServers`: it reports `connected`, the negotiated `protocol_version`, `tool_count`, and `stderr_tail` when a stdio child dies. A DISABLED entry is never started, so it will never report `connected`; enable it to learn anything.
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through `hoody-proxy`, not by connecting to the container directly.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "payload_too_large",
  "message": "request body exceeds the configured size limit"
}

Error Code	Title	Description	Resolution
`payload_too_large`	Payload too large	The request body exceeds the configured size cap (`MaxBodyBytes`).	Reduce the request body below the configured limit (default 8 MiB).

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded.	Honor the `Retry-After` header and retry.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor `Retry-After` and retry.

SDK usage

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

// Machine callers will receive 403 human_only — see the caution above.
await client.agent.mcp.probeMCPServer({
  session_id: 'sess_01HZX9ABCDEF',
  server: {
    name: 'filesystem',
    type: 'stdio',
    command: 'npx',
    args: ['-y', '@modelcontextprotocol/server-filesystem', '/home/me/projects']
  }
});

Reconnect all servers

`POST /api/v1/agent/mcp/reconnect`

Re-reads the settings layers and reconciles every live session’s MCP pool: servers that vanished or were re-pointed are revoked, the rest are reconnected, and a healthy unchanged server is NOT restarted. Revocation lands in EVERY live session before the response. Reconnection is AWAITED only for the session you named — awaited, not guaranteed: a server that will not start leaves connected false and still returns 200. Other sessions reconnect in the background, best-effort. Use it after editing a settings file by hand, or to recover a server that died.

Parameters

Name	In	Type	Required	Description
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container.
`X-Hoody-Realm`	header	string	No	Per-request realm selector.
`realm`	query	string	No	In-query alias of `X-Hoody-Realm`.

Request Body

Field	Type	Required	Description
`session_id`	string	Yes	Live session id.

{
  "session_id": "sess_01HZX9ABCDEF"
}

Responses

{
  "status": "ok",
  "sessions": 3,
  "revoked": 1,
  "deferred_sessions": 2,
  "deferred_started": true,
  "servers": [
    {
      "name": "filesystem",
      "transport": "stdio",
      "require_confirmation": false,
      "enabled": true,
      "connected": true,
      "protocol_version": "2025-03-26",
      "server_name": "filesystem",
      "server_version": "0.5.0",
      "tool_count": 8,
      "pid": 48239,
      "env_keys": ["LOG_LEVEL", "PATH"],
      "header_keys": []
    }
  ]
}

{
  "code": "bad_request",
  "message": "invalid request"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to an active-only / global-no-realm RPC.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through `hoody-proxy`, not by connecting to the container directly.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "payload_too_large",
  "message": "request body exceeds the configured size limit"
}

Error Code	Title	Description	Resolution
`payload_too_large`	Payload too large	The request body exceeds the configured size cap (`MaxBodyBytes`).	Reduce the request body below the configured limit (default 8 MiB).

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded.	Honor the `Retry-After` header and retry.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor `Retry-After` and retry.

SDK usage

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.agent.mcp.reconnectMCP({
  session_id: 'sess_01HZX9ABCDEF'
});