Skip to content
Hoody Documentation
Hoody.com
Download Page (.md)

Agent: MCP Servers

Section titled “Agent: MCP Servers”

These endpoints let you inspect, create, update, enable, disable, import, probe and reconnect Model Context Protocol (MCP) servers in the agent’s settings layers. Use them to manage the tool surface an agent can reach: stdio subprocesses for local tools, and HTTP/SSE for remote ones.

A configured MCP server is an ordinary subprocess or outbound HTTP client running with the operator’s privileges. It is not sandboxed, confined or pre-approved. The daemon scrubs the child’s environment of ambient provider credentials and the platform token, which keeps a leaked secret from being passed to a child the operator did not author — that is the limit of the platform’s guarantee.

Write flow

Section titled “Write flow”

Four endpoints write the mcp_servers config: upsertMCPServer, deleteMCPServer, setMCPServerEnabled and importMCPServers. Every one of them requires both a single-use nonce from beginMCPWrite and the current mcp_servers hash passed as expect_hash.

  • expect_hash is always required. A first write into a settings file that does not exist yet states its expectation with the empty-array hash that listMCPServers or beginMCPWrite return for a missing file — omitting the field is a request error, not a no-op.
  • A mismatch returns 409 mcp_conflict. Re-read the current hash, re-apply your change on top of what is there now, and re-issue the write. A blind retry will not help.
  • beginMCPWrite binds the nonce to {session, op, resolved path}. A nonce minted for op:upsert cannot be used for op:delete, and a nonce minted for user cannot be used to write project.
  • Revocation lands in every live session before the write’s response returns. Reconnection for sessions other than the one you named is best-effort and may be skipped under sustained write pressure — those sessions pick the change up on the next write or an explicit reconnectMCP.

Reading flow

Section titled “Reading flow”

listMCPServers, parseMCPImport and probeMCPServer do not write. parseMCPImport is a pure parser — useful for previewing an import before committing. probeMCPServer is human-only: probing starts a subprocess (stdio) or makes an outbound request to a caller-chosen URL (http/sse), and the gateway stamps every forwarded HTTP call with the machine marker, so a machine caller receives 403 human_only. Get the same information from upsertMCPServer followed by listMCPServers.

List configured MCP servers

Section titled “List configured MCP servers”

GET /api/v1/agent/mcp/servers

Section titled “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, negotiated protocol_version, tool_count, pid, revocation reason, recent stderr_tail). Credential values are never returned — env and headers are reported as key NAMES only (env_keys, header_keys), because a redacted value invites a client to write the placeholder back as the real secret. Each files entry carries the content hash to pass as expect_hash on a subsequent write.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
session_idquerystringYesLive session id. The route folds against this session’s settings layers; foldHookSession reads ?session_id.
realmquerystringNoPer-request realm selector — the in:query alias of the X-Hoody-Realm header (read only when the header is absent): global or a 24-hex id. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes.
X-Hoody-CwdheaderstringNoPer-request working-directory scope: the .hoody project layer / record cwd / tool+workflow cwd. Required by routes that resolve a cwd (e.g. POST /todos; createTodo also accepts a body cwd).
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override selecting which on-disk .hoody install a stateless read/write resolves (HoodyPaths).
X-Hoody-ContainerheaderstringNoPer-request bound remote container (omitted = local). Rejected (400) on routes with no container dimension.
X-Hoody-RealmheaderstringNoPer-request realm selector: global or a 24-hex id (also accepted as ?realm=). Rejected (400 realm_scope_unsupported) on active-only / no-realm routes.

Response

Section titled “Response”
{
  "status": "ok",
  "servers": [
    {
      "name": "github",
      "layer": "user",
      "enabled": true,
      "transport": "stdio",
      "require_confirmation": false,
      "connected": true,
      "protocol_version": "2024-11-05",
      "server_name": "github-mcp",
      "server_version": "1.2.3",
      "tool_count": 12,
      "pid": 48211,
      "command": "github-mcp-server",
      "args": ["--readonly"],
      "env_keys": ["GITHUB_TOKEN"],
      "header_keys": []
    },
    {
      "name": "playwright",
      "layer": "project",
      "enabled": true,
      "transport": "http",
      "require_confirmation": true,
      "connected": false,
      "url": "https://playwright.example/mcp",
      "header_keys": ["X-API-Key"]
    }
  ],
  "files": [
    {
      "path": "/home/operator/.hoody/settings.json",
      "scope": "user",
      "hash": "sha256:9b1f8c3a7d2e0c4a1f3b5d7e9c2a4b6d"
    },
    {
      "path": "/work/proj/.hoody/settings.json",
      "scope": "project",
      "hash": "sha256:3d2a4f6b8c0e1d3a5b7c9d1e3f5a7b9c"
    }
  ],
  "warnings": []
}

SDK

Section titled “SDK”
Terminal window
curl -X GET "https://prj-7f3a9b-cont-2e4d8c-agent-1.us-east-1.containers.hoody.com/api/v1/agent/mcp/servers?session_id=sess-abc123" \
  -H "Authorization: Bearer $HOODY_TOKEN"

Begin an MCP config write

Section titled “Begin an MCP config write”

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

Section titled “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

Section titled “Parameters”
NameInTypeRequiredDescription
X-Hoody-CwdheaderstringNoPer-request working-directory scope: the .hoody project layer / record cwd / tool+workflow cwd. Required by routes that resolve a cwd (e.g. POST /todos; createTodo also accepts a body cwd).
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override selecting which on-disk .hoody install a stateless read/write resolves (HoodyPaths).
X-Hoody-ContainerheaderstringNoPer-request bound remote container (omitted = local). Rejected (400) on routes with no container dimension.
X-Hoody-RealmheaderstringNoPer-request realm selector: global or a 24-hex id (also accepted as ?realm=). Rejected (400 realm_scope_unsupported) on active-only / no-realm routes.
realmquerystringNoPer-request realm selector — the in:query alias of the X-Hoody-Realm header (read only when the header is absent): global or a 24-hex id. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes.

Request Body

Section titled “Request Body”
NameTypeRequiredDescription
session_idstringYesLive session id (MCP config is resolved against the session’s settings layers).
opstringYesWhich write the nonce authorizes. The minted nonce is valid for this op alone. One of: upsert, delete, set_enabled, import.
scopestringNoSettings layer to write. Defaults to user, or project when there is no user layer (which is the case under --config-dir). One of: user, project, local.

Response

Section titled “Response”
{
  "status": "ok",
  "nonce": "nce_5c8a9d7e1f2b3a4c6e8f9d0a1b2c3d4e",
  "path": "/home/operator/.hoody/settings.json",
  "hash": "sha256:9b1f8c3a7d2e0c4a1f3b5d7e9c2a4b6d"
}

SDK

Section titled “SDK”
Terminal window
curl -X POST "https://prj-7f3a9b-cont-2e4d8c-agent-1.us-east-1.containers.hoody.com/api/v1/agent/mcp/write-intents" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "sess-abc123",
    "op": "upsert",
    "scope": "user"
  }'

Create or update an MCP server

Section titled “Create or update an MCP server”

PUT /api/v1/agent/mcp/servers

Section titled “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 beginMCPWrite nonce for op:upsert. 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

Section titled “Parameters”
NameInTypeRequiredDescription
X-Hoody-CwdheaderstringNoPer-request working-directory scope: the .hoody project layer / record cwd / tool+workflow cwd. Required by routes that resolve a cwd (e.g. POST /todos; createTodo also accepts a body cwd).
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override selecting which on-disk .hoody install a stateless read/write resolves (HoodyPaths).
X-Hoody-ContainerheaderstringNoPer-request bound remote container (omitted = local). Rejected (400) on routes with no container dimension.
X-Hoody-RealmheaderstringNoPer-request realm selector: global or a 24-hex id (also accepted as ?realm=). Rejected (400 realm_scope_unsupported) on active-only / no-realm routes.
realmquerystringNoPer-request realm selector — the in:query alias of the X-Hoody-Realm header (read only when the header is absent): global or a 24-hex id. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes.

Request Body

Section titled “Request Body”
NameTypeRequiredDescription
session_idstringYesLive session id.
noncestringYesSingle-use nonce from beginMCPWrite minted for op:upsert and this scope; the RPC fails closed without it.
scopestringNoSettings layer to write. Must match the scope the nonce was minted for. One of: user, project, local.
expect_hashstringYesThe mcp_servers hash you last read, as returned by beginMCPWrite or listMCPServers. Required: a mismatch returns a conflict instead of overwriting a concurrent edit, and a first write into a file that does not exist yet states its expectation with the empty-array hash rather than omitting this.
serverobjectYesThe server entry. Fields include: name (letters, digits, _ and -, max 64 chars, no __, may not be hoody or mcp — both are reserved namespaces, case-insensitive); 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).

Response

Section titled “Response”
{
  "status": "ok",
  "sessions": 1,
  "revoked": 1,
  "deferred_sessions": 0,
  "deferred_started": true,
  "servers": [
    {
      "name": "github",
      "layer": "user",
      "enabled": true,
      "transport": "stdio",
      "require_confirmation": false,
      "connected": true,
      "protocol_version": "2024-11-05",
      "server_name": "github-mcp",
      "server_version": "1.2.3",
      "tool_count": 12,
      "pid": 48211,
      "command": "github-mcp-server",
      "args": ["--readonly"],
      "env_keys": ["GITHUB_TOKEN"],
      "header_keys": []
    }
  ],
  "path": "/home/operator/.hoody/settings.json",
  "hash": "sha256:7c0a9b3d2e1f4a6c8b0d9e2f1a3c5b7d"
}

SDK

Section titled “SDK”
Terminal window
curl -X PUT "https://prj-7f3a9b-cont-2e4d8c-agent-1.us-east-1.containers.hoody.com/api/v1/agent/mcp/servers" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "sess-abc123",
    "nonce": "nce_5c8a9d7e1f2b3a4c6e8f9d0a1b2c3d4e",
    "scope": "user",
    "expect_hash": "sha256:9b1f8c3a7d2e0c4a1f3b5d7e9c2a4b6d",
    "server": {
      "name": "github",
      "type": "stdio",
      "command": "github-mcp-server",
      "args": ["--readonly"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    }
  }'

Delete an MCP server

Section titled “Delete an MCP server”

DELETE /api/v1/agent/mcp/servers

Section titled “DELETE /api/v1/agent/mcp/servers”

Removes one mcp_servers entry from the named settings layer. Requires the beginMCPWrite nonce for op:delete. 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

Section titled “Parameters”
NameInTypeRequiredDescription
X-Hoody-CwdheaderstringNoPer-request working-directory scope: the .hoody project layer / record cwd / tool+workflow cwd. Required by routes that resolve a cwd (e.g. POST /todos; createTodo also accepts a body cwd).
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override selecting which on-disk .hoody install a stateless read/write resolves (HoodyPaths).
X-Hoody-ContainerheaderstringNoPer-request bound remote container (omitted = local). Rejected (400) on routes with no container dimension.
X-Hoody-RealmheaderstringNoPer-request realm selector: global or a 24-hex id (also accepted as ?realm=). Rejected (400 realm_scope_unsupported) on active-only / no-realm routes.
realmquerystringNoPer-request realm selector — the in:query alias of the X-Hoody-Realm header (read only when the header is absent): global or a 24-hex id. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes.

Request Body

Section titled “Request Body”
NameTypeRequiredDescription
session_idstringYesLive session id.
noncestringYesSingle-use nonce from beginMCPWrite minted for op:delete and this scope.
scopestringNoSettings layer to write. Must match the scope the nonce was minted for. One of: user, project, local.
namestringYesThe server name to remove.
expect_hashstringYesThe mcp_servers hash you last read.

Response

Section titled “Response”
{
  "status": "ok",
  "sessions": 1,
  "revoked": 1,
  "deferred_sessions": 0,
  "deferred_started": true,
  "servers": [],
  "path": "/home/operator/.hoody/settings.json",
  "hash": "sha256:5b2e7c9a1d3f8a4b6c0d2e4f8a1b3c5d"
}

SDK

Section titled “SDK”
Terminal window
curl -X DELETE "https://prj-7f3a9b-cont-2e4d8c-agent-1.us-east-1.containers.hoody.com/api/v1/agent/mcp/servers" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "sess-abc123",
    "nonce": "nce_5c8a9d7e1f2b3a4c6e8f9d0a1b2c3d4e",
    "scope": "user",
    "name": "github",
    "expect_hash": "sha256:9b1f8c3a7d2e0c4a1f3b5d7e9c2a4b6d"
  }'

Enable or disable an MCP server

Section titled “Enable or disable an MCP server”

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

Section titled “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 beginMCPWrite nonce for op:set_enabled. Disabling revokes the server in live sessions immediately.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
X-Hoody-CwdheaderstringNoPer-request working-directory scope: the .hoody project layer / record cwd / tool+workflow cwd. Required by routes that resolve a cwd (e.g. POST /todos; createTodo also accepts a body cwd).
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override selecting which on-disk .hoody install a stateless read/write resolves (HoodyPaths).
X-Hoody-ContainerheaderstringNoPer-request bound remote container (omitted = local). Rejected (400) on routes with no container dimension.
X-Hoody-RealmheaderstringNoPer-request realm selector: global or a 24-hex id (also accepted as ?realm=). Rejected (400 realm_scope_unsupported) on active-only / no-realm routes.
realmquerystringNoPer-request realm selector — the in:query alias of the X-Hoody-Realm header (read only when the header is absent): global or a 24-hex id. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes.

Request Body

Section titled “Request Body”
NameTypeRequiredDescription
session_idstringYesLive session id.
noncestringYesSingle-use nonce from beginMCPWrite minted for op:set_enabled and this scope.
scopestringNoSettings layer to write. Must match the scope the nonce was minted for. One of: user, project, local.
namestringYesThe server name.
enabledbooleanYestrue to enable, false to disable.
expect_hashstringYesThe mcp_servers hash you last read.

Response

Section titled “Response”
{
  "status": "ok",
  "sessions": 1,
  "revoked": 1,
  "deferred_sessions": 0,
  "deferred_started": true,
  "servers": [
    {
      "name": "github",
      "layer": "user",
      "enabled": false,
      "transport": "stdio",
      "require_confirmation": false,
      "connected": false,
      "command": "github-mcp-server",
      "args": ["--readonly"],
      "env_keys": ["GITHUB_TOKEN"],
      "header_keys": []
    }
  ],
  "path": "/home/operator/.hoody/settings.json",
  "hash": "sha256:8d1c4a7b2e9f3a5c6d8b0e2f4a7c9d1b"
}

SDK

Section titled “SDK”
Terminal window
curl -X POST "https://prj-7f3a9b-cont-2e4d8c-agent-1.us-east-1.containers.hoody.com/api/v1/agent/mcp/servers/enable" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "sess-abc123",
    "nonce": "nce_5c8a9d7e1f2b3a4c6e8f9d0a1b2c3d4e",
    "scope": "user",
    "name": "github",
    "enabled": false,
    "expect_hash": "sha256:9b1f8c3a7d2e0c4a1f3b5d7e9c2a4b6d"
  }'

Import MCP servers from another tool’s config

Section titled “Import MCP servers from another tool’s config”

POST /api/v1/agent/mcp/import

Section titled “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 beginMCPWrite nonce for op:import.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
X-Hoody-CwdheaderstringNoPer-request working-directory scope: the .hoody project layer / record cwd / tool+workflow cwd. Required by routes that resolve a cwd (e.g. POST /todos; createTodo also accepts a body cwd).
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override selecting which on-disk .hoody install a stateless read/write resolves (HoodyPaths).
X-Hoody-ContainerheaderstringNoPer-request bound remote container (omitted = local). Rejected (400) on routes with no container dimension.
X-Hoody-RealmheaderstringNoPer-request realm selector: global or a 24-hex id (also accepted as ?realm=). Rejected (400 realm_scope_unsupported) on active-only / no-realm routes.
realmquerystringNoPer-request realm selector — the in:query alias of the X-Hoody-Realm header (read only when the header is absent): global or a 24-hex id. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes.

Request Body

Section titled “Request Body”
NameTypeRequiredDescription
session_idstringYesLive session id.
noncestringYesSingle-use nonce from beginMCPWrite minted for op:import and this scope.
scopestringNoSettings layer to write. Must match the scope the nonce was minted for. One of: user, project, local.
documentstringNoA pasted config document in any supported dialect. Mutually exclusive with servers.
serversarrayNoExplicit server entries, in hoody’s own shape. Mutually exclusive with document.
replacebooleanNoOverwrite entries whose name already exists. Without it, a collision aborts the whole import.
expect_hashstringYesThe mcp_servers hash you last read.

Response

Section titled “Response”
{
  "status": "ok",
  "sessions": 1,
  "revoked": 0,
  "deferred_sessions": 0,
  "deferred_started": true,
  "servers": [
    {
      "name": "github",
      "layer": "user",
      "enabled": false,
      "transport": "stdio",
      "require_confirmation": false,
      "connected": false,
      "command": "github-mcp-server",
      "args": ["--readonly"],
      "env_keys": ["GITHUB_TOKEN"],
      "header_keys": []
    },
    {
      "name": "playwright",
      "layer": "user",
      "enabled": false,
      "transport": "http",
      "require_confirmation": false,
      "connected": false,
      "url": "https://playwright.example/mcp",
      "header_keys": ["X-API-Key"]
    }
  ],
  "path": "/home/operator/.hoody/settings.json",
  "hash": "sha256:4e7c2a9b1d5f8c3a6e0b2d4f8a1c3e5b",
  "imported": 2
}

SDK

Section titled “SDK”
Terminal window
curl -X POST "https://prj-7f3a9b-cont-2e4d8c-agent-1.us-east-1.containers.hoody.com/api/v1/agent/mcp/import" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "sess-abc123",
    "nonce": "nce_5c8a9d7e1f2b3a4c6e8f9d0a1b2c3d4e",
    "scope": "user",
    "document": "{\"mcpServers\":{\"github\":{\"command\":\"github-mcp-server\",\"args\":[\"--readonly\"]}}}",
    "expect_hash": "sha256:9b1f8c3a7d2e0c4a1f3b5d7e9c2a4b6d"
  }'

Preview an MCP config import

Section titled “Preview an MCP config import”

POST /api/v1/agent/mcp/parse

Section titled “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

Section titled “Parameters”
NameInTypeRequiredDescription
X-Hoody-CwdheaderstringNoPer-request working-directory scope: the .hoody project layer / record cwd / tool+workflow cwd. Required by routes that resolve a cwd (e.g. POST /todos; createTodo also accepts a body cwd).
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override selecting which on-disk .hoody install a stateless read/write resolves (HoodyPaths).
X-Hoody-ContainerheaderstringNoPer-request bound remote container (omitted = local). Rejected (400) on routes with no container dimension.
X-Hoody-RealmheaderstringNoPer-request realm selector: global or a 24-hex id (also accepted as ?realm=). Rejected (400 realm_scope_unsupported) on active-only / no-realm routes.
realmquerystringNoPer-request realm selector — the in:query alias of the X-Hoody-Realm header (read only when the header is absent): global or a 24-hex id. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes.

Request Body

Section titled “Request Body”
NameTypeRequiredDescription
session_idstringYesLive session id.
documentstringYesA config document in any supported dialect.

Response

Section titled “Response”
{
  "status": "ok",
  "dialect": "claude",
  "servers": [
    {
      "name": "github",
      "type": "stdio",
      "command": "github-mcp-server",
      "args": ["--readonly"],
      "env_keys": ["GITHUB_TOKEN"],
      "header_keys": []
    }
  ],
  "count": 1
}

SDK

Section titled “SDK”
Terminal window
curl -X POST "https://prj-7f3a9b-cont-2e4d8c-agent-1.us-east-1.containers.hoody.com/api/v1/agent/mcp/parse" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "sess-abc123",
    "document": "{\"mcpServers\":{\"github\":{\"command\":\"github-mcp-server\",\"args\":[\"--readonly\"]}}}"
  }'

Probe an MCP server without saving it

Section titled “Probe an MCP server without saving it”

POST /api/v1/agent/mcp/probe

Section titled “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. HUMAN-ONLY: probing starts a process (stdio) or makes an outbound request to a caller-chosen URL (http/sse), so a machine caller may not self-approve it and receives 403 human_only. The deny list is enforced on the candidate config before anything is started.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
X-Hoody-CwdheaderstringNoPer-request working-directory scope: the .hoody project layer / record cwd / tool+workflow cwd. Required by routes that resolve a cwd (e.g. POST /todos; createTodo also accepts a body cwd).
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override selecting which on-disk .hoody install a stateless read/write resolves (HoodyPaths).
X-Hoody-ContainerheaderstringNoPer-request bound remote container (omitted = local). Rejected (400) on routes with no container dimension.
X-Hoody-RealmheaderstringNoPer-request realm selector: global or a 24-hex id (also accepted as ?realm=). Rejected (400 realm_scope_unsupported) on active-only / no-realm routes.
realmquerystringNoPer-request realm selector — the in:query alias of the X-Hoody-Realm header (read only when the header is absent): global or a 24-hex id. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes.

Request Body

Section titled “Request Body”
NameTypeRequiredDescription
session_idstringYesLive session id (supplies the deny list and transport policy).
serverobjectYesThe candidate entry, same shape as upsertMCPServer’s server.

Response

Section titled “Response”

This route has no 2xx response. Every forwarded HTTP call is machine-stamped; the only path is 403 human_only. Other non-2xx statuses remain reachable for malformed input.

{
  "code": "bad_request",
  "message": "invalid request"
}
Error CodeTitleDescriptionResolution
bad_requestBad requestThe request was malformed or carried invalid parameters.Correct the request body or query parameters.
realm_scope_unsupportedRealm scope unsupportedA 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.

SDK

Section titled “SDK”
Terminal window
curl -X POST "https://prj-7f3a9b-cont-2e4d8c-agent-1.us-east-1.containers.hoody.com/api/v1/agent/mcp/probe" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "sess-abc123",
    "server": {
      "name": "github",
      "type": "stdio",
      "command": "github-mcp-server",
      "args": ["--readonly"]
    }
  }'

Reload MCP config and reconnect

Section titled “Reload MCP config and reconnect”

POST /api/v1/agent/mcp/reconnect

Section titled “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 this after editing a settings file by hand, or to recover a server that died.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
X-Hoody-CwdheaderstringNoPer-request working-directory scope: the .hoody project layer / record cwd / tool+workflow cwd. Required by routes that resolve a cwd (e.g. POST /todos; createTodo also accepts a body cwd).
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override selecting which on-disk .hoody install a stateless read/write resolves (HoodyPaths).
X-Hoody-ContainerheaderstringNoPer-request bound remote container (omitted = local). Rejected (400) on routes with no container dimension.
X-Hoody-RealmheaderstringNoPer-request realm selector: global or a 24-hex id (also accepted as ?realm=). Rejected (400 realm_scope_unsupported) on active-only / no-realm routes.
realmquerystringNoPer-request realm selector — the in:query alias of the X-Hoody-Realm header (read only when the header is absent): global or a 24-hex id. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes.

Request Body

Section titled “Request Body”
NameTypeRequiredDescription
session_idstringYesLive session id.

Response

Section titled “Response”
{
  "status": "ok",
  "sessions": 1,
  "revoked": 0,
  "deferred_sessions": 0,
  "deferred_started": true,
  "servers": [
    {
      "name": "github",
      "layer": "user",
      "enabled": true,
      "transport": "stdio",
      "require_confirmation": false,
      "connected": true,
      "protocol_version": "2024-11-05",
      "server_name": "github-mcp",
      "server_version": "1.2.3",
      "tool_count": 12,
      "pid": 48211,
      "command": "github-mcp-server",
      "args": ["--readonly"],
      "env_keys": ["GITHUB_TOKEN"],
      "header_keys": []
    }
  ]
}

SDK

Section titled “SDK”
Terminal window
curl -X POST "https://prj-7f3a9b-cont-2e4d8c-agent-1.us-east-1.containers.hoody.com/api/v1/agent/mcp/reconnect" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "sess-abc123"
  }'