MCP Integration

AFK supports the Model Context Protocol (MCP), letting agents connect to approved external tools and services such as databases, APIs, browsers, and SaaS platforms.

How MCP works in AFK

MCP servers add external capabilities to agent sessions. Configure the servers you want to make available, then let agents discover and use those tools when a task requires them.

• Configured servers can be enabled per session from the MCP picker.
• Agents discover available tools before calling them.
• Unused MCP servers do not need to be running for every session.
• Sensitive values should be stored in Secretsand referenced from MCP config.

Config format

MCP configuration is stored in JSON files. Three scopes exist (higher priority first):

1. <projectDir>/.afk/mcp.local.json — private, not committed to version control
2. <projectDir>/.afk/mcp.json — version-controlled, shared with the team
3. ~/.afk/mcp.json — daemon-owned user file on the selected machine; edit it from Preferences → MCP. Project and local files stay with the checkout and are edited from /mcp.

Stdio server

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

HTTP/SSE server

{
  "mcpServers": {
    "my-api": {
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${secrets.api_token}"
      }
    }
  }
}

OAuth-protected HTTP server

{
  "mcpServers": {
    "figma": {
      "url": "https://mcp.figma.com/mcp",
      "oauth": true,
      "oauth_scope": "files:read"
    }
  }
}

Built-in system providers

AFK registers common providers automatically. They can be enabled via the session MCP picker without editing config files:

Connecting Chrome DevTools

The chrome-devtools provider attaches to a Chrome session you explicitly approve, so an agent can inspect an authenticated tab and use WebMCP tools exposed by the page. In Chrome 144 or later, open chrome://inspect/#remote-debugging, enable remote debugging, then approve the connection when AFK starts the provider.

Connecting gives the selected agent access to open tabs in that Chrome profile, including authenticated sites. Close sensitive tabs before connecting. For isolated, repeatable automation, use playwrightinstead.

OAuth flow

For MCP servers that require OAuth, AFK guides you through authorization from the session MCP picker:

1. Set "oauth": true on the server entry in your MCP config.
2. Open the session's MCP picker and click Connect on the OAuth-protected server row.
3. Complete the provider authorization flow.
4. AFK stores the resulting grant securely and uses it automatically for future requests to that server. In org sessions, each member authorizes their own external account.

To disconnect, open the MCP picker for that session and click Disconnect.

Reloading MCP config

After editing a config file, use the reload tool or the /reload browser command to re-read configs without restarting the session.

MCP elicitation

MCP servers can ask for structured mid-task input. AFK shows those requests as browser forms, sends the response back to the server, and keeps the resolved interaction in the session transcript for auditability.

You can also use hooks to apply team-specific handling for repeated MCP prompts. See Hooks Reference.

Plugin MCP servers

Plugins can contribute MCP servers for repeatable team workflows. Store sensitive values in Secrets and reference them from plugin configuration rather than committing raw tokens.

AFK as an MCP server

AFK can expose an authenticated MCP endpoint so approved external clients can start, message, inspect, wait for, resume, or stop AFK sessions. Use this for controlled automation from other tools or internal workflows.

Config scope priority example

# Project config — checked into git, shared with team
# <projectDir>/.afk/mcp.json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
    }
  }
}

# Local override — gitignored, personal
# <projectDir>/.afk/mcp.local.json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Volumes/fast-ssd/projects"]
    }
  }
}

The local file wins for that machine without changing the committed team config.