> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aident.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP Server Setup
> Connect Claude Code, Cursor, or any MCP-compatible tool to Aident
Connect your favorite AI assistant to Aident Loadout integrations and Playbook workflows through the Model Context Protocol (MCP).
## Prerequisites
* Active [Aident account](https://app.aident.ai)
* Connected integrations in **Capabilities**
* An MCP-compatible client
## Step 1: Add Server URL
Use the product MCP URL for the package you need. Loadout is the default integration surface:
```
https://app.aident.ai/loadout/mcp
```
For Playbook workflows, configure a separate MCP server at:
```
https://app.aident.ai/playbook/mcp
```
Run in your terminal:
```bash theme={null}
claude mcp add --transport http aident https://app.aident.ai/loadout/mcp
```
Or add to `~/.claude.json`:
```json theme={null}
{
"mcpServers": {
"aident": {
"type": "http",
"url": "https://app.aident.ai/loadout/mcp"
}
}
}
```
Add to your config file:
* **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
* **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
```json theme={null}
{
"mcpServers": {
"aident": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://app.aident.ai/loadout/mcp"]
}
}
}
```
Or on **Pro/Max/Team/Enterprise** plans: **Settings → Connectors → Add** and enter `https://app.aident.ai/loadout/mcp`.
Add to `.cursor/mcp.json` in your project root:
```json theme={null}
{
"mcpServers": {
"aident": {
"url": "https://app.aident.ai/loadout/mcp"
}
}
}
```
Add to `.vscode/mcp.json` in your project root:
```json theme={null}
{
"servers": {
"aident": {
"type": "http",
"url": "https://app.aident.ai/loadout/mcp"
}
}
}
```
Add to `~/.codeium/windsurf/mcp_config.json`:
```json theme={null}
{
"mcpServers": {
"aident": {
"serverUrl": "https://app.aident.ai/loadout/mcp"
}
}
}
```
Run in your terminal:
```bash theme={null}
codex mcp add aident --url https://app.aident.ai/loadout/mcp
```
Or add to `~/.codex/config.toml` (or `.codex/config.toml` for a trusted project):
```toml theme={null}
[mcp_servers.aident]
url = "https://app.aident.ai/loadout/mcp"
```
Verify the server is configured:
```bash theme={null}
codex mcp list
```
Add to `~/.gemini/settings.json`:
```json theme={null}
{
"mcpServers": {
"aident": {
"httpUrl": "https://app.aident.ai/loadout/mcp"
}
}
}
```
Any MCP-compatible client (Goose, Kiro, OpenCode, Antigravity, Factory, etc.) can connect using the server URL `https://app.aident.ai/loadout/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.
## 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://app.aident.ai/loadout/mcp`
3. Check that your browser can reach app.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: 24 hours
* 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": "" }`
3. Authorize in browser
4. Retry the operation
### Connection Timeout
* Check firewall allows outbound HTTPS to app.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.