MCP · Daemon API

On this page

The agent's MCP servers: configured and live state

GET/agents/{id}/mcp

Operation getAgentMcpAuthBearer token

Path parameters

Name	Type	Description
`id`required	string	Loaded agent: its id, handle or name. example: agent-1

Responses

Status Description Body

200 Servers AgentMcpDiagnostics

agentIdrequired

string

Agent id

configuredrequired array<object>

5 fields of configured

`name`required	string
`transport`	string
`command`	string
`args`	array<string>
`toolCount`required	integer

statesrequired array<McpServerState>

7 fields of states

namerequired string

statusrequired

string

One of stopped, connecting, connected, error, installing

error string

connectedAt integer

restartCountrequired integer

toolCountrequired integer

logsrequired array<object>

3 fields of logs

`timestamp`required	integer
`stream`required	string	One of `stdout`, `stderr`, `system`
`message`required	string

Errors 401 · 403 · 404

401	Missing or wrong bearer token (`unauthorized`)
403	The request guard refused it: Host header not allowed (`host_not_allowed`, DNS-rebinding protection) or a browser cross-site request (`cross_origin`)`host_not_allowedcross_origin`
404	Unknown agent (or the named resource: loop, task, file, …)

Error bodies use the error format.

Example

Request

curl "http://127.0.0.1:7385/agents/agent-1/mcp" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

The agent's MCP servers (same as GET …/mcp)

GET/agents/{id}/runtime/mcp

Operation getAgentRuntimeMcpAuthBearer token

Path parameters

Name	Type	Description
`id`required	string	Loaded agent: its id, handle or name. example: agent-1

Responses

Status	Description	Body
200	Servers	AgentMcpDiagnostics
Fields as in AgentMcpDiagnostics above.

Errors 401 · 403 · 404

401	Missing or wrong bearer token (`unauthorized`)
403	The request guard refused it: Host header not allowed (`host_not_allowed`, DNS-rebinding protection) or a browser cross-site request (`cross_origin`)`host_not_allowedcross_origin`
404	Unknown agent (or the named resource: loop, task, file, …)

Error bodies use the error format.

Example

Request

curl "http://127.0.0.1:7385/agents/agent-1/runtime/mcp" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Attach or update an MCP server config

POST/agents/{id}/mcp/servers

Operation attachAgentMcpServerAuthBearer token

Saved to the agent config; the server connects at the next start, or now with POST …/mcp/servers/{serverName}/restart.

Path parameters

Name	Type	Description
`id`required	string	Loaded agent: its id, handle or name. example: agent-1

Request bodyapplication/json · McpAttachBody · required

server (alias serverConfig) with name and transport.

Field Type Description

serverrequired object

20 fields of server · McpServerConfig

namerequired string

transportrequired

string

One of stdio, http

command string

args array<string>

url string

oauth boolean

headers map<string, string>

header_env array<object>

bearer_token_env_var string

env map<string, string>

env_keys array<string>

env_schema array<object>

npm_package string

pypi_package string

source string

available_tools array<object>

tool_call_timeout_ms integer

restricted boolean

run_location

string

One of host, shared

credential_files array<object>

3 fields of credential_files

`path`required	string
`required`	boolean
`write_back`	boolean

serverConfig

object

Fields as in McpServerConfig above.

Responses

Status Description Body

200 Attached McpAttachResponse

agentIdrequired

string

Agent id

serverNamerequired string

successrequired

boolean

Value true

alreadyAttachedrequired boolean

configrequired

object

The agent's ADF v0.2 config (adf_config). Only the most used fields are listed; the full shape is the ADF spec's AgentConfig. Secret values never appear here.

25 fields of config · AgentConfig

adf_versionrequired

string

Value 0.2

idrequired

string

Agent id (stable, the daemon addresses the agent by it)

namerequired string

descriptionrequired string

handle string

icon string

staterequired

string

Display (fleet-map) state of an agent

One of active, idle, hibernate, suspended, off

autonomousrequired boolean

autostart boolean

modelrequired object

9 fields of model · ModelConfig

providerrequired

string

Provider id (app provider or one of the agent's own providers)

model_idrequired string

temperature number | null

max_tokens integer | null

top_p number | null

reasoning

object

Provider-agnostic reasoning ("thinking") config

multimodal object

3 fields of multimodal

`image`	boolean
`audio`	boolean
`video`	boolean

params array<object>

2 fields of params

`key`required	string
`value`required	string

provider_params object

instructionsrequired string

contextrequired

object

compact_threshold, audit, dynamic_instructions

toolsrequired

array<object>

Tool declarations

5 fields of tools

`name`required	string
`enabled`required	boolean
`visible`	boolean
`restricted`	boolean
`locked`	boolean

triggersrequired

map<string, TriggerConfig>

on_startup, on_inbox, on_outbox, on_file_change, on_chat, on_timer, on_tool_call, on_task_create, on_task_complete, on_logs, on_llm_call

3 fields of triggers

enabledrequired boolean

targetsrequired array<TriggerTarget>

11 fields of targets

`scope`required	string	One of `agent`, `system`
`lambda`	string	System scope: `path/file.ts:functionName`
`command`	string	System scope: shell command (alternative to lambda)
`warm`	boolean
`filter`	object
`debounce_ms`	integer
`interval_ms`	integer
`batch_ms`	integer
`batch_count`	integer
`locked`	boolean
`loop`	string	Cognition loop this target wakes; absent = main

locked boolean

securityrequired object

limitsrequired object

messagingrequired

object

mode (proactive | respond_only | listen_only), receive, network, …

mcp object

2 fields of mcp

serversrequired array<McpServerConfig>

20 fields of servers

namerequired string

transportrequired

string

One of stdio, http

command string

args array<string>

url string

oauth boolean

headers map<string, string>

header_env array<object>

bearer_token_env_var string

env map<string, string>

env_keys array<string>

env_schema array<object>

npm_package string

pypi_package string

source string

available_tools array<object>

tool_call_timeout_ms integer

restricted boolean

run_location

string

One of host, shared

credential_files array<object>

3 fields of credential_files

`path`required	string
`required`	boolean
`write_back`	boolean

new_tools_restricted boolean

adapters

map<string, AdapterInstanceConfig>

Channel adapters by type

4 fields of adapters

enabledrequired boolean

config

object

Adapter-specific settings (no secrets: tokens are credentials)

policy object

limits object

1 field of limits

max_attachment_size

integer

Bytes

providers array<AgentProviderConfig>

8 fields of providers

idrequired

string

anthropic, openai, … or custom:<id>

typerequired

string

One of anthropic, openai, openai-compatible, openrouter

namerequired string

baseUrlrequired string

preset string

defaultModel string

params array<object>

2 fields of params

`key`required	string
`value`required	string

requestDelayMs integer

loops

array<LoopConfig>

Inner (side) loops; main is implicit

8 fields of loops

`name`required	string	pattern: ^[a-z0-9][a-z0-9_-]{0,31}$
`goal`required	string	Becomes the loop's instructions
`enabled`required	boolean
`autostart`	boolean
`autonomous`	boolean
`model`	object	Fields as in ModelConfig above.
`compact_threshold`	integer \| null
`tools`	array<string>	Absolute allow-list, intersected with the host's enabled tools

ws_connections array<object>

serving object

locked_fields array<string>

metadatarequired

object

created_at, updated_at, author, tags, version

Errors 400 · 401 · 403 · 404 · 500

400	Invalid request: missing or malformed field, query parameter or body. A body Fastify cannot parse gets Fastify's own shape (`statusCode`, `code`, `error`, `message`).`bad_requestFST_ERR_CTP_EMPTY_JSON_BODY`
401	Missing or wrong bearer token (`unauthorized`)
403	The request guard refused it: Host header not allowed (`host_not_allowed`, DNS-rebinding protection) or a browser cross-site request (`cross_origin`)`host_not_allowedcross_origin`
404	Unknown agent (or the named resource: loop, task, file, …)
500	Unexpected runtime failure

Error bodies use the error format.

Example

Request

curl -X POST "http://127.0.0.1:7385/agents/agent-1/mcp/servers" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "server": {
    "name": "filesystem",
    "transport": "stdio",
    "npm_package": "@modelcontextprotocol/server-filesystem"
  }
}'

Detach an MCP server and delete its credentials

DELETE/agents/{id}/mcp/servers/{serverName}

Operation detachAgentMcpServerAuthBearer token

Removes the server config and the matching mcp:* identity rows.

Path parameters

Name	Type	Description
`id`required	string	Loaded agent: its id, handle or name. example: agent-1
`serverName`required	string	MCP server name in the agent config example: filesystem

Query parameters

Name	Type	Description
`credentialNamespace`	string	Credential namespace to delete (default: the server's package or name)

Responses

Status Description Body

200 Detached McpDetachResponse

`agentId`required	string	Agent id
`serverName`required	string
`success`required	boolean	Value `true`
`deletedCredentials`required	integer
`config`required	object	The agent's ADF v0.2 config (adf_config). Only the most used fields are listed; the full shape is the ADF spec's AgentConfig. Secret values never appear here. Fields as in AgentConfig above.

Errors 401 · 403 · 404 · 500

401	Missing or wrong bearer token (`unauthorized`)
403	The request guard refused it: Host header not allowed (`host_not_allowed`, DNS-rebinding protection) or a browser cross-site request (`cross_origin`)`host_not_allowedcross_origin`
404	Unknown agent (or the named resource: loop, task, file, …)
500	Unexpected runtime failure

Error bodies use the error format.

Example

Request

curl -X DELETE "http://127.0.0.1:7385/agents/agent-1/mcp/servers/filesystem" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Connect one configured MCP server now

POST/agents/{id}/mcp/servers/{serverName}/restart

Operation restartAgentMcpServerAuthBearer token

The same connect the agent's own mcp_restart tool does (host or container routing, the agent's sealed credentials, tool discovery). Use it after POST …/mcp/servers (attached servers connect at the next start otherwise) or to retry a failed server. 404 for an unknown server; 409 when the agent is not running here. No body.

Path parameters

Name	Type	Description
`id`required	string	Loaded agent: its id, handle or name. example: agent-1
`serverName`required	string	MCP server name in the agent config example: filesystem

Responses

Status Description Body

200 Connect outcome McpRestartResponse

`agentId`required	string	Agent id
`serverName`required	string
`success`required	boolean	Connected with at least one tool
`toolsDiscovered`required	integer
`location`	string
`error`	string
`hostDenied`	string
`stderrTail`	array<string>

Errors 401 · 403 · 404 · 409 · 500

401	Missing or wrong bearer token (`unauthorized`)
403	The request guard refused it: Host header not allowed (`host_not_allowed`, DNS-rebinding protection) or a browser cross-site request (`cross_origin`)`host_not_allowedcross_origin`
404	Unknown agent (or the named resource: loop, task, file, …)
409	The resource is in a state that does not allow this now
500	Unexpected runtime failure

Error bodies use the error format.

Example

Request

curl -X POST "http://127.0.0.1:7385/agents/agent-1/mcp/servers/filesystem/restart" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Daemon-wide MCP registrations (values redacted)

GET/runtime/mcp

Operation getRuntimeMcpAuthBearer token

Responses

Status Description Body

200 Registrations McpRegistrationsDiagnostics

serversrequired array<object>

16 fields of servers

idrequired string

namerequired string

typerequired string

npmPackage string

pypiPackage string

command string

args array<string>

url string

managedrequired boolean

version string

credentialStoragerequired string

envrequired array<object>

2 fields of env

`key`required	string
`hasValue`required	boolean

headersrequired array<object>

2 fields of headers

`key`required	string
`hasValue`required	boolean

headerEnvrequired array<object>

2 fields of headerEnv

`header`required	string
`env`required	string

bearerTokenEnvVarrequired string | null

toolCallTimeoutrequired integer | null

Errors 401 · 403

401	Missing or wrong bearer token (`unauthorized`)
403	The request guard refused it: Host header not allowed (`host_not_allowed`, DNS-rebinding protection) or a browser cross-site request (`cross_origin`)`host_not_allowedcross_origin`

Error bodies use the error format.

Example

Request

curl "http://127.0.0.1:7385/runtime/mcp" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"