> ## 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 API Reference

> Reference for the Aident MCP tool suite

The Aident MCP Server exposes the full suite of Aident tools across auth, capabilities, skills, integrations, playbooks, templates, and dashboard. All tools are accessible through any MCP-compatible client after [setup](/documentation/mcp-server-setup).

## Auth Tools

### auth\_status

Check your current authentication status. Always accessible, even without scopes.

**No input required.**

### auth\_logout

Revoke your access token and log out. Use this to switch accounts — reconnect after logout to sign in with a different account.

**No input required.**

## Capabilities, Skills & Discovery

### Capability execution contract

Design PRD: Actions & Skills Naming Alignment Phase 4.

`capabilities_execute` is the execution tool. It accepts `{ name, input }`, tries dotted names as integration Actions first, and falls back to a Skill only when the integration Action is not found and a Skill exists with the same full dotted name. Integration execution errors return the Action error payload and do not fall back to Skills. Plain names route directly through Skill execution.

Integration Actions return the Action output directly without `durationMs` or `executionTimeMs`. Skill execution returns `{ success, output?, error?, executionTimeMs }`.

### capabilities\_search

Search capabilities by query, including Actions, Skills, and integrations. Supports keyword, semantic, and hybrid search modes.

| Parameter | Type      | Required    | Description                                                         |
| --------- | --------- | ----------- | ------------------------------------------------------------------- |
| `query`   | string    | Yes (min 2) | Search query — supports `*`, `-`, `"phrases"`, `\|` operators       |
| `types`   | string\[] | No          | Filter by type: `integration`, `skill`                              |
| `scope`   | object    | No          | Scope filtering: `{ integrationId?, category? }`                    |
| `mode`    | string    | No          | Search mode: `keyword`, `semantic`, or `hybrid` (default: `hybrid`) |
| `limit`   | number    | No          | Max results, 1-50 (default: 20)                                     |

### capabilities\_get

Look up details for a known integration or capability by exact name. By default only `description` is returned; request additional parts as needed.

MCP exposes this as `capabilities_get`; internally it delegates to the capability runtime's `capability_read_details` tool.

| Parameter | Type      | Required | Description                                                                                                                                                        |
| --------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `name`    | string    | Yes      | Exact integration ID (e.g., `gmail_tools`) or capability name (e.g., `gmail.send_email`)                                                                           |
| `parts`   | string\[] | No       | Sections to include. Integration: `description`, `agentFriendlyInstructions`, `availableSkills`. Skill: `description`, `inputSchema`, `outputSchema`, `sourceCode` |

### capabilities\_execute

Execute a capability by name. Accepts either a skill name (e.g., `send_email_skill`) or an integration action in `integrationId.ACTION_NAME` form (e.g., `gmail_tools.send_email`). If required integrations are missing, returns connection instructions.

| Parameter | Type   | Required | Description                                                 |
| --------- | ------ | -------- | ----------------------------------------------------------- |
| `name`    | string | Yes      | Capability name — skill name or `integrationId.ACTION_NAME` |
| `input`   | object | No       | Input data matching the capability's schema                 |

Response shape:

* Skills return `{ success, output?, error?, executionTimeMs }`.
* Integration Actions return the Action output directly. This shape omits `durationMs` and `executionTimeMs`.

## Vault Tool

### vault

Check, connect, or disconnect third-party integrations through Aident Vault.

| Parameter       | Type                    | Required | Description                                                      |
| --------------- | ----------------------- | -------- | ---------------------------------------------------------------- |
| `action`        | string                  | Yes      | `status`, `connect`, or `disconnect`                             |
| `integrationId` | string                  | No       | Specific integration ID. Required for `connect` and `disconnect` |
| `confirmed`     | boolean                 | No       | Confirm credit usage for first-party integrations                |
| `credentials`   | Record\<string, string> | No       | User-provided credentials (API keys, tokens, etc.)               |

## Playbook Tools

### playbooks\_list

List your playbooks with status and trigger info.

| Parameter | Type   | Required | Description               |
| --------- | ------ | -------- | ------------------------- |
| `limit`   | number | No       | Max results (default: 20) |
| `offset`  | number | No       | Pagination offset         |

### playbooks\_get

Get playbook details including content and trigger configuration.

| Parameter    | Type   | Required | Description                |
| ------------ | ------ | -------- | -------------------------- |
| `playbookId` | string | Yes      | Playbook editor session ID |

### playbooks\_generate

Generate a new playbook from a natural language description.

| Parameter | Type   | Required | Description                                            |
| --------- | ------ | -------- | ------------------------------------------------------ |
| `prompt`  | string | Yes      | Description of the playbook to generate (min 10 chars) |

### playbooks\_execute

Execute a playbook. Returns an execution session ID for tracking.

| Parameter    | Type   | Required | Description                          |
| ------------ | ------ | -------- | ------------------------------------ |
| `playbookId` | string | Yes      | Playbook editor session ID           |
| `input`      | object | No       | Optional input data for the playbook |

### playbooks\_trigger\_activate

Enable or disable a playbook's trigger.

| Parameter    | Type    | Required | Description                              |
| ------------ | ------- | -------- | ---------------------------------------- |
| `playbookId` | string  | Yes      | Playbook editor session ID               |
| `enabled`    | boolean | Yes      | Whether to enable or disable the trigger |

### playbooks\_history

Get execution history for a specific playbook.

| Parameter    | Type   | Required | Description                |
| ------------ | ------ | -------- | -------------------------- |
| `playbookId` | string | Yes      | Playbook editor session ID |
| `limit`      | number | No       | Max results (default: 10)  |

## Template Tools

### templates\_search

Search for playbook templates by keyword or category.

| Parameter  | Type   | Required | Description        |
| ---------- | ------ | -------- | ------------------ |
| `query`    | string | No       | Search query       |
| `category` | string | No       | Filter by category |

### templates\_list

List available templates with optional category filtering.

| Parameter  | Type   | Required | Description               |
| ---------- | ------ | -------- | ------------------------- |
| `category` | string | No       | Filter by category        |
| `limit`    | number | No       | Max results (default: 20) |
| `offset`   | number | No       | Pagination offset         |

### templates\_get

Get detailed template information including description and required integrations.

| Parameter    | Type   | Required | Description |
| ------------ | ------ | -------- | ----------- |
| `templateId` | string | Yes      | Template ID |

### templates\_instantiate

Create a new playbook from a template.

| Parameter    | Type   | Required | Description                      |
| ------------ | ------ | -------- | -------------------------------- |
| `templateId` | string | Yes      | Template ID                      |
| `name`       | string | No       | Custom name for the new playbook |

## Dashboard Tools

### dashboard\_overview

List playbooks with active triggers or running executions.

**No input required.**

### executions\_get

Get execution details including status, messages, and results.

| Parameter     | Type   | Required | Description          |
| ------------- | ------ | -------- | -------------------- |
| `executionId` | string | Yes      | Execution session ID |

### executions\_list

List recent executions across all playbooks.

| Parameter | Type   | Required | Description               |
| --------- | ------ | -------- | ------------------------- |
| `limit`   | number | No       | Max results (default: 20) |
| `offset`  | number | No       | Pagination offset         |

### executions\_messages

Get simplified chat messages for a running or completed execution. Useful for polling progress.

| Parameter   | Type   | Required | Description                    |
| ----------- | ------ | -------- | ------------------------------ |
| `sessionId` | string | Yes      | Session ID to get messages for |

## Scopes

Tools are organized into permission scopes. Access is granted during OAuth authorization:

| Scope                             | Tools                                                                        |
| --------------------------------- | ---------------------------------------------------------------------------- |
| `capabilities:search`             | capabilities\_search                                                         |
| `capabilities:read`               | capabilities\_get                                                            |
| `capabilities:execute`            | capabilities\_execute                                                        |
| `integrations:read`               | vault status, capabilities\_integration\_list                                |
| `integrations:connect`            | vault connect, vault disconnect                                              |
| `playbooks:read`                  | playbooks\_list, playbooks\_get, playbooks\_history                          |
| `playbooks:create`                | playbooks\_generate                                                          |
| `playbooks:execute`               | playbooks\_execute                                                           |
| `playbooks:manage`                | playbooks\_trigger\_activate                                                 |
| `templates:read`                  | templates\_search, templates\_list, templates\_get                           |
| `templates:use`                   | templates\_instantiate                                                       |
| `dashboard:read`                  | dashboard\_overview, executions\_get, executions\_list, executions\_messages |
| `sandbox:read`, `sandbox:execute` | Used by sandbox-capable tools                                                |

The `auth` tool is always accessible regardless of scopes.