Dynamic Attach and Detach

MCP servers can be attached to and detached from a running agent without restarting it. This is useful for temporarily granting access to additional tools or for debugging.

Attach a server to a running agent

ash mcp attach <agent-id> <mcp-name>

The server must already be registered via ash mcp add.

# Register the server definition (if not already done)
ash mcp add github stdio \
  --command /usr/local/bin/github-mcp \
  --description "GitHub tools"

# Attach to a running agent
ash mcp attach 550e8400-e29b-41d4-a716-446655440000 github

On success, agentd prints the list of tools that were added:

Attached mcp server 'github' to agent 550e8400...
Tools added:
  mcp.github.list_prs
  mcp.github.create_issue
  mcp.github.get_repo

Operator override

The attach command checks that the target agent has the tool.invoke:mcp.<name>.* capability. An operator token bypasses this check:

ash mcp attach <agent-id> <mcp-name> --operator <token>

Use operator override with care; it grants tool access beyond the agent's declared capabilities.

Detach a server from a running agent

ash mcp detach <agent-id> <mcp-name>

agentd:

1. Sends shutdown + exit notifications to the server (Stdio) or closes the HTTP session.
2. Unregisters all mcp.<name>.* tools from the agent's ToolRegistry.
3. Returns the list of removed tools.

Detached mcp server 'github' from agent 550e8400...
Tools removed:
  mcp.github.list_prs
  mcp.github.create_issue
  mcp.github.get_repo

Any in-flight tool invocations at the moment of detach will receive a NotAttached error.

Capability requirements

Multiple attachments

The same MCP server definition can be attached to multiple agents simultaneously. Each attachment creates an independent McpSession with its own subprocess or HTTP connection.

ash mcp attach agent-1 github
ash mcp attach agent-2 github   # separate session, separate subprocess

Workflow example

# 1. Register definition once
ash mcp add analytics http \
  --url https://analytics.internal/mcp \
  --description "Analytics query server"

# 2. Check running agents
ash list

# 3. Attach to a specific agent for a debugging session
ash mcp attach <agent-id> analytics

# 4. Agent now calls mcp.analytics.* tools...

# 5. Detach when done
ash mcp detach <agent-id> analytics

Audit log

All attach and detach operations are recorded in the audit log:

ash audit --agent <agent-id>

Entries include: timestamp, operation (McpAttach/McpDetach), server name, and tools added/removed.