---
url: /handbook/connect/mcp.md
description: >-
  Connect an advisor's AI assistant to a DutyGraph workspace over MCP, with
  scoped personal tokens.
---

# MCP for advisors

An advisor can connect an AI assistant, such as Claude Code, to their DutyGraph workspace. The assistant can then add accounts, import CSV files, start research, read the Company Snapshot and the Company Repo, and prepare outreach.

The advisor MCP server is a second way to do what the app does. It is not a second set of rules. Each tool calls the app's own route, as the advisor who owns the token.

## Create a token

### Open the panel

Sign in as an advisor. Open **Settings › MCP access**, then **Connect an AI assistant (MCP)**.

### Name it and choose scopes

Enter a name, for example "Claude Code on my laptop". Choose the scopes (below).

### Choose when it expires

Choose 30 days, 90 days (the default), 1 year or No expiry.

### Copy it once

Select **Create token**. Copy the token now. It starts with `dgp_`. DutyGraph shows it once and keeps only its SHA-256 hash.

The token list shows each token's name, scopes, creation date, last use and expiry. **Revoke** stops a token at once. A token cannot create or revoke tokens.

The shared sample login cannot create tokens, because every visitor shares that workspace.

## Scopes

| Scope | What the assistant can do |
| --- | --- |
| **Read** (always on) | See companies, accounts, research status, the Company Snapshot, Company Repo files and outreach drafts |
| **Write** | Add accounts and contacts, import CSV files, start Preview or Snapshot research, prepare and edit outreach drafts. Write does not send email. |
| **Send email** (off by default) | Send a prepared outreach draft. Turn it on only if you review each draft before you tell the assistant to send it. |

A fourth scope, `request_agents`, belongs to employees. It cannot be combined with these. See [Request from your AI](../governance/request-from-your-ai.md).

## Tools

| Tool | Scope | What it does |
| --- | --- | --- |
| `list_companies` | read | Companies in the workspace |
| `list_accounts` | read | Accounts with stage, research level and primary contact |
| `get_account` | read | One account: stage, engagement, contacts, research authorizations, drafts, recent events |
| `get_research_status` | read | The latest research runs and whether a research source is ready |
| `get_company_snapshot` | read | The findings the Company Snapshot shows, with their sources |
| `get_company_repo_index` | read | The Company Repo index: each file's path, title and state |
| `read_company_repo_file` | read | One Company Repo file, with its state and content |
| `list_outreach_drafts` | read | Drafts, recipient, sender gaps, quota and research signals |
| `add_account` | write | One prospect, with the same duplicate checks as **Accounts › Add account** |
| `import_accounts_csv` | write | A CSV of accounts. Previews unless `apply: true`. |
| `add_contact` | write | A contact on an account |
| `run_research` | write | Starts Preview or Snapshot research and returns the run id |
| `import_roster_csv` | write | A company's team list. Previews unless `apply: true`. Invites nobody. |
| `draft_outreach` | write | Prepares the outreach note from the app's template and research signals |
| `edit_outreach_draft` | write | Changes the subject and body. The content checks run again. |
| `send_outreach` | send_email | Sends a saved draft through the app's Send path |

`read_company_repo_file` can read a saved agent manifest's Repo file (`manifests/<slug>.md`), so an assistant can read the manifest the builder made.

## Connect

The endpoint is `<your DutyGraph origin>/api/mcp`. Send the token as `Authorization: Bearer <token>`.

**Claude Code**

Run the command the panel shows:

```bash
claude mcp add --transport http dutygraph https://<your-dutygraph-host>/api/mcp \
  --header "Authorization: Bearer <token>"
```

**Claude Desktop**

Claude Desktop needs the local `mcp-remote` bridge and Node.js. Add a server to Claude Desktop's configuration in **Settings › Developer**, then restart Claude Desktop:

```json
{
  "mcpServers": {
    "dutygraph": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://<your-dutygraph-host>/api/mcp",
               "--header", "Authorization:${DUTYGRAPH_AUTH}"],
      "env": { "DUTYGRAPH_AUTH": "Bearer <token>" }
    }
  }
}
```

DutyGraph shows this configuration in the employee's **Connect your AI** panel. The advisor panel shows only the Claude Code command. The endpoint and header are the same.

**Other assistants**

Add a Streamable HTTP MCP server with the URL `<origin>/api/mcp` and the header `Authorization: Bearer <token>`. The server is stateless: it answers `POST` with JSON.

Claude web custom connectors and ChatGPT need OAuth sign-in. That is **Planned**.

## Safety rules

* **Same user, same rules.** A token acts as its advisor, inside the advisor's workspace. Another workspace's company returns "not found".
* **Audited, marked as MCP.** Audit events and account events written during a tool call name the token's user as the actor, with `via: "mcp"` and the token id. Creating and revoking a token are audit events too. Read-only tool calls leave no audit record yet.
* **No contact with employees.** No tool invites or emails a company's people.
* **Outreach goes through the app's checks.** `send_outreach` uses the same Send path as the app: sender identity, suppression lists, the footer and unsubscribe, approval and limits. If a check warns, the tool refuses and says "Needs approval in the app".
* **No secrets.** No tool returns provider keys, email settings or private links.
* **No decisions.** No tool can approve, change or deny an agent request.

A missing, revoked or expired token gets HTTP 401. Failed token checks count against a per-address limit.

## The other MCP surfaces

* Employees use the same endpoint with a `request_agents` token. See [Request from your AI](../governance/request-from-your-ai.md).
* Issued agents use a separate endpoint and credential. See [Agent gateway](../governance/agent-gateway.md).

::: info
**Status.** **Built:** the advisor MCP server, tokens with read, write and send email scopes, the 16 tools, audit marking and token revoke. **Simulated:** none on this page. **Planned:** OAuth sign-in for web and mobile connectors, and an audit record for every read-only tool call.
:::
