On this page

The agent's MCP servers: configured and live state

GET/agents/{id}/mcp

Operation getAgentMcpAuthBearer token

Path parameters

NameTypeDescription
idrequiredstring

Loaded agent: its id, handle or name.

example: agent-1

Responses

StatusDescriptionBody
200ServersAgentMcpDiagnostics
agentIdrequiredstring

Agent id

configuredrequiredarray<object>
5 fields of configured
namerequiredstring
transportstring
commandstring
argsarray<string>
toolCountrequiredinteger
statesrequiredarray<McpServerState>
7 fields of states
namerequiredstring
statusrequiredstring

One of stopped, connecting, connected, error, installing, needs_sign_in

errorstring
connectedAtinteger
restartCountrequiredinteger
toolCountrequiredinteger
logsrequiredarray<object>
3 fields of logs
timestamprequiredinteger
streamrequiredstring

One of stdout, stderr, system

messagerequiredstring
Errors 401 · 403 · 404
401Missing or wrong bearer token (unauthorized)
403The 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
404Unknown 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

NameTypeDescription
idrequiredstring

Loaded agent: its id, handle or name.

example: agent-1

Responses

StatusDescriptionBody
200ServersAgentMcpDiagnostics

Fields as in AgentMcpDiagnostics above.

Errors 401 · 403 · 404
401Missing or wrong bearer token (unauthorized)
403The 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
404Unknown 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

NameTypeDescription
idrequiredstring

Loaded agent: its id, handle or name.

example: agent-1

Request bodyapplication/json · McpAttachBody · required

server (alias serverConfig) with name and transport.

FieldTypeDescription
serverrequiredobject
20 fields of server · McpServerConfig
namerequiredstring
transportrequiredstring

One of stdio, http

commandstring
argsarray<string>
urlstring
oauthboolean
headersmap<string, string>
header_envarray<object>
bearer_token_env_varstring
envmap<string, string>
env_keysarray<string>
env_schemaarray<object>
npm_packagestring
pypi_packagestring
sourcestring
available_toolsarray<object>
tool_call_timeout_msinteger
restrictedboolean
run_locationstring

One of host, shared

credential_filesarray<object>
3 fields of credential_files
pathrequiredstring
requiredboolean
write_backboolean
serverConfigobject

Fields as in McpServerConfig above.

Responses

StatusDescriptionBody
200AttachedMcpAttachResponse
agentIdrequiredstring

Agent id

serverNamerequiredstring
successrequiredboolean

Value true

alreadyAttachedrequiredboolean
configrequiredobject

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_versionrequiredstring

Value 0.2

idrequiredstring

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

namerequiredstring
descriptionrequiredstring
handlestring
iconstring
staterequiredstring

Display (fleet-map) state of an agent

One of active, idle, hibernate, suspended, off

autonomousrequiredboolean
autostartboolean
modelrequiredobject
9 fields of model · ModelConfig
providerrequiredstring

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

model_idrequiredstring
temperaturenumber | null
max_tokensinteger | null
top_pnumber | null
reasoningobject

Provider-agnostic reasoning ("thinking") config

multimodalobject
3 fields of multimodal
imageboolean
audioboolean
videoboolean
paramsarray<object>
2 fields of params
keyrequiredstring
valuerequiredstring
provider_paramsobject
instructionsrequiredstring
contextrequiredobject

compact_threshold, max_request_media_files, max_request_media_mb, compaction_model, audit, dynamic_instructions

toolsrequiredarray<object>

Tool declarations

5 fields of tools
namerequiredstring
enabledrequiredboolean
visibleboolean
restrictedboolean
lockedboolean
triggersrequiredmap<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
enabledrequiredboolean
targetsrequiredarray<TriggerTarget>
11 fields of targets
scoperequiredstring

One of agent, system

lambdastring

System scope: path/file.ts:functionName

commandstring

System scope: shell command (alternative to lambda)

warmboolean
filterobject
debounce_msinteger
interval_msinteger
batch_msinteger
batch_countinteger
lockedboolean
loopstring

Cognition loop this target wakes; absent = main

lockedboolean
securityrequiredobject
limitsrequiredobject
messagingrequiredobject

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

mcpobject
2 fields of mcp
serversrequiredarray<McpServerConfig>
20 fields of servers
namerequiredstring
transportrequiredstring

One of stdio, http

commandstring
argsarray<string>
urlstring
oauthboolean
headersmap<string, string>
header_envarray<object>
bearer_token_env_varstring
envmap<string, string>
env_keysarray<string>
env_schemaarray<object>
npm_packagestring
pypi_packagestring
sourcestring
available_toolsarray<object>
tool_call_timeout_msinteger
restrictedboolean
run_locationstring

One of host, shared

credential_filesarray<object>
3 fields of credential_files
pathrequiredstring
requiredboolean
write_backboolean
new_tools_restrictedboolean
adaptersmap<string, AdapterInstanceConfig>

Channel adapters by type

4 fields of adapters
enabledrequiredboolean
configobject

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

policyobject
limitsobject
1 field of limits
max_attachment_sizeinteger

Bytes

providersarray<AgentProviderConfig>
8 fields of providers
idrequiredstring

anthropic, openai, … or custom:<id>

typerequiredstring

One of anthropic, openai, openai-compatible, openrouter

namerequiredstring
baseUrlrequiredstring
presetstring
defaultModelstring
paramsarray<object>
2 fields of params
keyrequiredstring
valuerequiredstring
requestDelayMsinteger
loopsarray<LoopConfig>

Inner (side) loops; main is implicit

8 fields of loops
namerequiredstring

pattern: ^[a-z0-9][a-z0-9_-]{0,31}$

goalrequiredstring

Becomes the loop's instructions

enabledrequiredboolean
autostartboolean
autonomousboolean
modelobject

Fields as in ModelConfig above.

compact_thresholdinteger | null
toolsarray<string>

Absolute allow-list, intersected with the host's enabled tools

ws_connectionsarray<object>
servingobject
locked_fieldsarray<string>
metadatarequiredobject

created_at, updated_at, author, tags, version

Errors 400 · 401 · 403 · 404 · 500
400Invalid 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
401Missing or wrong bearer token (unauthorized)
403The 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
404Unknown agent (or the named resource: loop, task, file, …)
500Unexpected 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

NameTypeDescription
idrequiredstring

Loaded agent: its id, handle or name.

example: agent-1

serverNamerequiredstring

MCP server name in the agent config

example: filesystem

Query parameters

NameTypeDescription
credentialNamespacestring

Credential namespace to delete (default: the server's package or name)

Responses

StatusDescriptionBody
200DetachedMcpDetachResponse
agentIdrequiredstring

Agent id

serverNamerequiredstring
successrequiredboolean

Value true

deletedCredentialsrequiredinteger
configrequiredobject

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
401Missing or wrong bearer token (unauthorized)
403The 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
404Unknown agent (or the named resource: loop, task, file, …)
500Unexpected 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

NameTypeDescription
idrequiredstring

Loaded agent: its id, handle or name.

example: agent-1

serverNamerequiredstring

MCP server name in the agent config

example: filesystem

Responses

StatusDescriptionBody
200Connect outcomeMcpRestartResponse
agentIdrequiredstring

Agent id

serverNamerequiredstring
successrequiredboolean

Connected with at least one tool

toolsDiscoveredrequiredinteger
locationstring
errorstring
hostDeniedstring
stderrTailarray<string>
Errors 401 · 403 · 404 · 409 · 500
401Missing or wrong bearer token (unauthorized)
403The 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
404Unknown agent (or the named resource: loop, task, file, …)
409The resource is in a state that does not allow this now
500Unexpected 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

StatusDescriptionBody
200RegistrationsMcpRegistrationsDiagnostics
serversrequiredarray<object>
16 fields of servers
idrequiredstring
namerequiredstring
typerequiredstring
npmPackagestring
pypiPackagestring
commandstring
argsarray<string>
urlstring
managedrequiredboolean
versionstring
credentialStoragerequiredstring
envrequiredarray<object>
2 fields of env
keyrequiredstring
hasValuerequiredboolean
headersrequiredarray<object>
2 fields of headers
keyrequiredstring
hasValuerequiredboolean
headerEnvrequiredarray<object>
2 fields of headerEnv
headerrequiredstring
envrequiredstring
bearerTokenEnvVarrequiredstring | null
toolCallTimeoutrequiredinteger | null
Errors 401 · 403
401Missing or wrong bearer token (unauthorized)
403The 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"

Probe an MCP server

POST/admin/mcp/probe

Operation probeMcpServerAuthBearer token

Temporary connect and tool list; logs are kept for GET /admin/mcp/logs/{serverName}.

Request bodyapplication/json · McpProbeBody · required

FieldTypeDescription
namerequiredstring
transportstring

One of stdio, http

commandstring
argsarray<string>
urlstring
envmap<string, string>
headersmap<string, string>
headerEnvarray<object>
2 fields of headerEnv
keystring
valuestring
bearerTokenEnvVarstring

Responses

StatusDescriptionBody
200OKMcpProbeResult
successrequiredboolean
toolsrequiredarray<object>
errorstring
Errors 401 · 403
401Missing or wrong bearer token (unauthorized)
403The 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 -X POST "http://127.0.0.1:7385/admin/mcp/probe" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"string"}'

Connect test for an MCP registration

POST/admin/mcp/registration-test

Operation testMcpRegistrationAuthBearer token

Runs the real pipeline for the draft. Interactive steps (an OAuth authorization URL, the auth preflight’s Continue) appear in GET /admin/mcp/interactions while the test runs. Runs as a job: answers 202 at once. Interactive steps of this run are listed by GET /admin/mcp/interactions?jobId=; POST /jobs/{jobId}/cancel stops it and disconnects the server it started.

Request bodyapplication/json · McpRegistrationTestBody · required

FieldTypeDescription
registrationrequiredobject

The MCP server registration draft (McpServerRegistration)

credentialFilesarray<object>
2 fields of credentialFiles
pathrequiredstring
contentB64requiredstring

Responses

StatusDescriptionBody
202Started; poll GET /jobs/{jobId}. The finished job's result is a McpRegistrationTestResult.object
jobIdrequiredstring
jobrequiredobject
1 field of job
resultobject
9 fields of result · McpRegistrationTestResult
successrequiredboolean
errorstring
toolsrequiredarray<object>
locationrequiredstring

One of host, shared container, remote http

authRanrequiredboolean
oauthRanboolean
notesrequiredarray<string>
serverVersionstring
stderrTailarray<string>
Errors 401 · 403 · 429
401Missing or wrong bearer token (unauthorized)
403The 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
429Too many jobs run on this daemon at once (jobs.ts MAX_RUNNING, 128).

Error bodies use the error format.

Example

Request
curl -X POST "http://127.0.0.1:7385/admin/mcp/registration-test" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"registration":{}}'

Interactive steps of running MCP registration tests

GET/admin/mcp/interactions

Operation getMcpInteractionsAuthBearer token

Query parameters

NameTypeDescription
jobIdstring

Only the steps of this job

Responses

StatusDescriptionBody
200OKMcpInteractionsResponse
interactionsrequiredarray<McpInteraction>
9 fields of interactions
idrequiredstring
jobIdrequiredstring

The registration-test job the step belongs to

kindrequiredstring

One of open_url, confirm

staterequiredstring

timed_out: a confirm nobody answered within 5 minutes; the test went on without it and its result says so

One of pending, timed_out

serverNamestring
urlstring

open_url: the authorization page to open

authUrlOpenedboolean
messagerequiredstring
createdAtrequirednumber
Errors 401 · 403
401Missing or wrong bearer token (unauthorized)
403The 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/admin/mcp/interactions" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Answer an interactive step

POST/admin/mcp/interactions/{interactionId}/continue

Operation continueMcpInteractionAuthBearer token

Removes an open_url step; lets a waiting confirm step continue. A timed-out step cannot be answered (404).

Path parameters

NameTypeDescription
interactionIdrequiredstring

Interaction id

Responses

StatusDescriptionBody
200OKSuccessResponse
successrequiredboolean
Errors 401 · 403 · 404
401Missing or wrong bearer token (unauthorized)
403The 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
404Unknown agent (or the named resource: loop, task, file, …)

Error bodies use the error format.

Example

Request
curl -X POST "http://127.0.0.1:7385/admin/mcp/interactions/INTERACTION_ID/continue" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"
Response 200
{
  "success": true
}

MCP server logs

GET/admin/mcp/logs/{serverName}

Operation getMcpServerLogsAuthBearer token

A loaded agent’s live logs (agentId), else the logs kept from probe, test and agent runs.

Path parameters

NameTypeDescription
serverNamerequiredstring

Server name

Query parameters

NameTypeDescription
agentIdstring

Loaded agent id, handle or name

Responses

StatusDescriptionBody
200OKMcpServerLogsResponse
logsrequiredarray<object>
Errors 401 · 403
401Missing or wrong bearer token (unauthorized)
403The 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/admin/mcp/logs/SERVER_NAME" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

App-level MCP OAuth sign-in state

GET/admin/mcp/oauth/status

Operation getMcpOAuthStatusAuthBearer token

Query parameters

NameTypeDescription
urlstring

Remote server URL

Responses

StatusDescriptionBody
200OKMcpOAuthStatus
signedInrequiredboolean

A token is stored for the URL. The token itself is never returned.

Errors 401 · 403
401Missing or wrong bearer token (unauthorized)
403The 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/admin/mcp/oauth/status" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Sign out of an MCP OAuth remote

POST/admin/mcp/oauth/signout

Operation signOutMcpOAuthAuthBearer token

Request bodyapplication/json · McpOAuthUrlBody · required

FieldTypeDescription
urlrequiredstring

The remote server URL

Responses

StatusDescriptionBody
200OKSuccessErrorResponse
successrequiredboolean
errorstring

Why it did not succeed

Errors 401 · 403
401Missing or wrong bearer token (unauthorized)
403The 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 -X POST "http://127.0.0.1:7385/admin/mcp/oauth/signout" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"string"}'
Response 200
{
  "success": false,
  "error": "This approval is no longer pending — it was already resolved, timed out, or its agent stopped."
}

Ensure uv and Python on the daemon host

POST/admin/mcp/python-runtime

Operation ensureMcpPythonRuntimeAuthBearer token

Downloads uv and Python when missing. Runs as a job: answers 202 at once. Cancel stops waiting; a download already running finishes. While one runs, another request joins it (job.joined).

Responses

StatusDescriptionBody
202Started; poll GET /jobs/{jobId}. The finished job's result is a PythonRuntimeResult.object
jobIdrequiredstring
jobrequiredobject
1 field of job
resultobject
6 fields of result · PythonRuntimeResult
successrequiredboolean
uvAvailablerequiredboolean
uvVersionstring | null
pythonAvailablerequiredboolean
uvPathstring
errorstring
Errors 401 · 403 · 429
401Missing or wrong bearer token (unauthorized)
403The 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
429Too many jobs run on this daemon at once (jobs.ts MAX_RUNNING, 128).

Error bodies use the error format.

Example

Request
curl -X POST "http://127.0.0.1:7385/admin/mcp/python-runtime" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"