Skip to main content
Connect your favorite AI assistant to Aident Loadout integrations and Playbook workflows through the Model Context Protocol (MCP).

​
Prerequisites

​
Step 1: Add Server URL

Use the product MCP URL for the package you need. Loadout is the default integration surface: 
https://loadout.aident.ai/mcp
For Playbook workflows, configure a separate MCP server at: 
https://app.aident.ai/playbook/mcp
Run in your terminal:
claude mcp add --transport http aident https://loadout.aident.ai/mcp
Or add to ~/.claude.json:
{
  "mcpServers": {
    "aident": {
      "type": "http",
      "url": "https://loadout.aident.ai/mcp"
    }
  }
}
Add to your config file:
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "aident": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://loadout.aident.ai/mcp"]
    }
  }
}
Or on Pro/Max/Team/Enterprise plans: Settings → Connectors → Add and enter https://loadout.aident.ai/mcp.
Add to .cursor/mcp.json in your project root:
{
  "mcpServers": {
    "aident": {
      "url": "https://loadout.aident.ai/mcp"
    }
  }
}
Add to .vscode/mcp.json in your project root:
{
  "servers": {
    "aident": {
      "type": "http",
      "url": "https://loadout.aident.ai/mcp"
    }
  }
}
Add to ~/.codeium/windsurf/mcp_config.json:
{
  "mcpServers": {
    "aident": {
      "serverUrl": "https://loadout.aident.ai/mcp"
    }
  }
}
Run in your terminal:
codex mcp add aident --url https://loadout.aident.ai/mcp
Or add to ~/.codex/config.toml (or .codex/config.toml for a trusted project):
[mcp_servers.aident]
url = "https://loadout.aident.ai/mcp"
Verify the server is configured:
codex mcp list
Add to ~/.gemini/settings.json:
{
  "mcpServers": {
    "aident": {
      "httpUrl": "https://loadout.aident.ai/mcp"
    }
  }
}
Any MCP-compatible client (Goose, Kiro, OpenCode, Antigravity, Factory, etc.) can connect using the server URL https://loadout.aident.ai/mcp. Refer to your client’s documentation for where to add MCP server configurations.

​
Step 2: Authenticate

On first use, your MCP client will automatically:
  1. Discover Aident’s OAuth endpoints
  2. Open your browser for login (Google OAuth or magic link)
  3. Store your access token locally
No manual token management needed — the client handles everything.

​
Step 3: Verify Connection

In your MCP client, try asking your AI assistant to use Aident tools. You should see Aident tools available across auth, skills, integrations, playbooks, templates, and dashboard.

​
Optional: Migrate Local Integration Configs

After first-time setup, ask your agent to run aident integrations migrate-local --json if the host can run shell commands. The command scans known local MCP/agent config files, redacts secret-like values, and shows which supported integrations can be connected through Loadout. Connect all supported matches or a selected subset with aident integrations migrate-local --apply --integrationIds <ids> --json, or use the MCP vault tool for the selected Loadout integration IDs.

​
Switching Accounts

To log out or switch to a different Aident account, use the auth_logout tool, then reconnect to trigger a new sign-in flow.

​
Troubleshooting

​
Authentication Issues

If the OAuth flow doesn’t start automatically:
  1. Restart your MCP client
  2. Verify URL is exactly https://loadout.aident.ai/mcp
  3. Check that your browser can reach loadout.aident.ai

​
”No OAuth flow is in progress” when running complete_authentication

Some MCP clients (notably Claude Code) expose two complementary tools — authenticate (start the flow) and complete_authentication (finish it by pasting the callback URL). The PKCE code_verifier produced by authenticate is held in the client’s process memory. If that process restarts between the two tool calls (which can happen between message turns on long-lived agent sessions), the verifier is lost and complete_authentication returns No OAuth flow is in progress. Reliable workarounds:
  • Open the authorization URL immediately when prompted. The local loopback callback listener catches the redirect inside the same process, completing the flow before any state can be lost. This is the path that works without ever calling complete_authentication.
  • If you must paste back the callback URL, run authenticate and complete_authentication back-to-back within the same agent turn.
Server-side, Aident emits the standard WWW-Authenticate: Bearer resource_metadata=… header on 401 responses, so MCP clients can rediscover the OAuth endpoints automatically.

​
Token TTLs

  • Access token: 7 days
  • Refresh token: 30 days (rotated on each refresh)
  • Authorization code: 10 minutes
If your client supports automatic refresh, you should only see an interactive OAuth prompt every ~30 days. If you are re-authorizing more often, your client may not be persisting refresh tokens across sessions — check its token cache.

​
”Skill requires unauthenticated integrations”

The skill needs integrations you haven’t connected:
  1. Use vault with { "action": "status" } to see what’s connected
  2. Use vault with { "action": "connect", "integrationId": "<id>" }
  3. Authorize in browser
  4. Retry the operation

​
Connection Timeout

  • Check firewall allows outbound HTTPS to loadout.aident.ai
  • Configure proxy in MCP client if needed
  • Try disconnecting VPN temporarily

​
Tools Not Appearing

  1. Restart MCP client
  2. Verify URL in configuration file
  3. Re-authenticate if token expired (client should handle automatically)

​
Managing Your Connection

​
Revoking Access

  1. Open Connections from the left sidebar and go to MCP
  2. Revoke the connection from your MCP client or Aident’s MCP controls
  3. All MCP connections will stop working immediately
  4. Re-authenticate to reconnect

​
Multiple Clients

You can use the same Aident account across multiple MCP clients. Each client maintains its own OAuth tokens.