---
url: /reference/partners.md
description: >-
  What a partner firm can do with a client through DutyGraph's MCP server and
  CLI today, with every endpoint, tool and command.
---

# MCP and CLI for partners

A partner firm is a coaching firm, a consultancy or an AI transformation firm that runs DutyGraph engagements for its own clients. The partner works in its own DutyGraph workspace. The partner's AI assistant (for example Claude Code) or the `dutygraph` command-line tool (CLI) then does the engagement work through DutyGraph's Model Context Protocol (MCP) server.

This page lists only what is in the code today. Each section gives the status. Items that are not built are listed at the end.

## 1. The parts

| Part | Address | What it is |
| --- | --- | --- |
| Advisor MCP server | `POST <origin>/api/mcp` | The tools in section 4. Streamable HTTP, stateless, JSON answers. `GET` and `DELETE` return 405. |
| Setup guide for an AI | `GET <origin>/api/mcp/setup.md` | A public Markdown guide with no key in it. An AI reads it to connect itself. |
| OAuth sign-in | `<origin>/.well-known/oauth-authorization-server` and `/api/oauth/register`, `/api/oauth/token`, `/api/oauth/revoke` | Sign-in without a pasted key (section 2). |
| CLI | `dutygraph <command>` | A Node.js program (Node 20 or later), packaged for npm as `dutygraph`. It is an MCP client: every command calls the tools in section 4. |
| Client's people | `POST <origin>/api/mcp` with a person token | The tools a client's employee uses from their own AI (section 6). The partner does not hold these tokens. |

`<origin>` is the DutyGraph address, for example `https://dutygraph.com`. The CLI uses `https://dutygraph.com` when you give no `--origin`.

## 2. Sign in

A partner signs in as an **advisor**. Each tool acts as that advisor, with the same checks as the DutyGraph app.

### Make the partner workspace

Register as an advisor firm (firm name, postal address, reply-to address). DutyGraph makes a new workspace for the firm. The workspace starts with no companies.

### Get a token

Use one of two methods:

* **Personal access token.** Open **Settings › MCP access**. Give the token a name and choose scopes. Under **Companies**, choose all companies or only the company that is open. Choose when it expires: 1 to 365 days (90 is the default), or no expiry. DutyGraph shows the token one time. It starts with `dgp_`.
* **OAuth from the CLI.** Run `dutygraph login`. A browser opens and you allow the connection. This gives `read` and `write` only, for 30 days. It works only for a program on your own computer (a loopback address).

### Connect the assistant

Claude Code:

```bash
claude mcp add --transport http dutygraph <origin>/api/mcp --header "Authorization: Bearer <token>"
```

CLI: install it with `npm install -g dutygraph`. Then run `dutygraph login`, or `dutygraph login --token <token>`, or set the `DUTYGRAPH_TOKEN` environment variable.

### Scopes

| Scope | What it allows |
| --- | --- |
| `read` | Read companies, accounts, research, the Company Snapshot, the Company Repo, people, answers, onboarding and the call plan. Every advisor token needs `read`. |
| `write` | Add companies, people and files. Start research. Fill onboarding answers. Make drafts. Nothing is sent. |
| `send_email` | Send a prepared question request or outreach email. Off by default. OAuth sign-in never gives it, so use a personal access token. |

One advisor can have 20 live tokens. Revoke a token in **Settings › MCP access**, or with `dutygraph logout` for a CLI sign-in. A missing, wrong, revoked or expired token gets HTTP 401. Failed token checks count against a limit for each network address.

## 3. Which clients a partner sees

* A token belongs to one advisor in one workspace. The token text holds the workspace id. The database applies row-level security for that workspace on every call.
* A partner's token reaches **only the companies in the partner's own workspace**. It cannot read or change another firm's companies.
* By default an advisor token reaches every company in its workspace.
* A token can be **limited to chosen companies**. Such a token lists and opens only those companies. Another company answers "not found". The token cannot add or import companies. `whoami` and `get_cli_identity` show the limit.
* Every tool call goes through the app's own route. The route checks permissions, versions, duplicates and limits. The audit record marks the call `via: "mcp"` with the token id.
* No tool returns provider keys, email settings or private sign-in links.

## 4. Advisor tools, by engagement step

Each tool takes a `companyId` (from `list_companies`), except where the table says otherwise. Most write tools take an optional `idempotencyKey`. The 3 document upload tools require it. A retry is safe only when you send the **same key and the same input** again. If you leave the key out, DutyGraph makes a new one for each call, so a retry after a lost answer can make a second record. A tool without its scope returns `SCOPE_REQUIRED`.

### 4.1 See who you are and your clients

| Tool | Scope | What it does | CLI |
| --- | --- | --- | --- |
| `get_cli_identity` | read | Shows the token's scopes and the advisor's name and id. | `whoami` |
| `list_companies` | read | Lists the companies in the workspace. | `companies`, `use <name or id>` |
| `list_accounts` | read | Lists accounts (client and prospect companies) with stage, research level and main contact. | none |
| `get_account` | read | Shows one account: stage, contacts, research permissions, outreach drafts, recent events. | none |

### 4.2 Add a client company

| Tool | Scope | What it does | CLI |
| --- | --- | --- | --- |
| `add_client` | write | Adds a company that is already the partner's client. Give how the engagement was agreed (for example a signed proposal and its reference) and who approved it. The engagement starts active, or waits for a second approver when the firm's rules need one. Nothing is sent. | `client add --name --method --note [--reference]` |
| `add_account` | write | Adds one **prospect** company with its website and first contact. It makes the company and its account. Duplicate websites and contacts are refused with the existing id. Nothing is sent. | `pitch new --name --website --contact --email` |
| `import_accounts_csv` | write | Adds up to 200 companies from CSV (company, website, contact name, title, email). Preview first; `apply: true` writes. | none |
| `add_contact` | write | Adds a contact to an account. | none |

### 4.3 Research the company

| Tool | Scope | What it does | CLI |
| --- | --- | --- | --- |
| `run_research` | write | Starts `preview` (public basics) or `snapshot` research. It records the research permission first when needed. | `research run --level preview\|snapshot` |
| `get_research_status` | read | Shows the latest research runs. | `research status` |
| `get_company_snapshot` | read | Shows the research findings, each with state, confidence and source types. | none |
| (document intake) | write | Sends the partner's own sourced research as a document, marked "not confirmed". | `research add <file.md> --source URL` |

### 4.4 Import the org chart and people

| Tool | Scope | What it does | CLI |
| --- | --- | --- | --- |
| `import_roster_csv` | write | Imports the team list from CSV: name, email, role, team, and optional `manager_email` and `external_id`. `manager_email` sets who reports to whom. Preview first; `apply: true` writes. It invites and emails nobody. | `roster import <file.csv> [--apply]` |
| `add_person` | write | Adds one person, with an optional manager email. It invites and emails nobody. | `person add` |
| `update_person` | write | Changes a person on the version you read. Marking a person as left revokes their open links. | `person fix` |
| `get_team_status` | read | Lists people, their latest request, answers and confirmed Task Cards. | `team` |

### 4.5 Import files about the company

| Tool | Scope | What it does | CLI |
| --- | --- | --- | --- |
| `begin_advisor_document` | write | Starts an upload of one file, 4 MB at most. | `repo push` (for new files in a pulled Repo) |
| `upload_advisor_document_chunk` | write | Uploads one numbered part of the file with its SHA-256. | (same) |
| `finish_advisor_document` | write | Checks the file and queues it for conversion. It does not add the file to the Company Repo; the advisor accepts what it proposes in the app. | (same) |
| `list_company_documents` | read | Lists published company documents. Private and restricted documents show their details only. | none |
| `read_company_document` | read | Reads one published document. | none |

File types: PDF, Word, Excel, CSV, PowerPoint, PNG, JPEG, plain text and Markdown.

### 4.6 Load the executive session (onboarding)

Onboarding is DutyGraph's North Star session: the company's vision, business model and goals, the team list with who reports to whom, and each person's questions and answers. A partner that already ran an executive vision session can load its results here.

| Tool | Scope | What it does | CLI |
| --- | --- | --- | --- |
| `get_onboarding_status` | read | Shows how far onboarding is: questions answered, and for each person their manager, status and answers. | `onboarding status` |
| `get_onboarding_readout` | read | Returns all onboarding answers as one Markdown document. | `onboarding readout [--out FILE.md]` |
| `fill_onboarding_answers` | write | Fills answers from Markdown (`# <file name>`, then `## <what the question fills>` and the answer). With no person, it fills the session answers. With a person, it fills that person's answers. Preview first. | `onboarding fill <FILE.md> [--person EMAIL] [--apply]` |
| `load_onboarding_transcript` | write | Drafts the North Star session answers from a call transcript with the company's AI. Preview first. With apply, it keeps the transcript and saves the drafts you checked. An answered question is kept unless replace is set. | `onboarding transcript <FILE.txt> [--apply] [--replace]` |
| `get_onboarding` | read | Returns the whole onboarding state, with its revision. | `onboarding export [--out FILE.json]` |
| `save_onboarding` | write | Saves the whole state on the revision you read. If someone saved after you read, it refuses with `VERSION_CONFLICT`. It never emails anyone. | `onboarding import <FILE.json> [--apply]` |

### 4.7 Ask people questions

| Tool | Scope | What it does | CLI |
| --- | --- | --- | --- |
| `create_request` | write | Makes a draft request of 1 to 10 questions for one person, and shows the email. Nothing is sent. | `ask <email> "question" ...` |
| `send_request` | write + send_email | Sends a draft request by email, after the advisor says yes. It must name the recipient's address. | `ask ... --send` |
| `list_requests` | read | Lists requests and response times. | `requests [--times]` |
| `list_arrivals` | read | Lists answers that came back and the Repo files they fill. The answer text is not returned. | `inbox [--since 2d]` |
| `nudge_person` | write | Previews or sends a short reminder to a person's DutyGraph app: add Task Cards, finish a draft, go on with an interview, answer a request. | `nudge <email> --reason ... [--send]` |

### 4.8 Read the work: Company Repo, Task Cards and Strategy Cards

The Company Repo is the company's record as Markdown files: people, duties, Task Cards (`tasks/<name>/task.md`), strategy and more. DutyGraph compiles it from its records. Each file says how far a person confirmed it.

| Tool | Scope | What it does | CLI |
| --- | --- | --- | --- |
| `get_company_repo_index` | read | Lists the Repo files, with state and counts. Optional folder filter. | none |
| `read_company_repo_file` | read | Reads one Repo file. | none |
| `export_company_repo` | read | Exports the Repo one page at a time, with a hash for each file. | `repo export`, `repo pull [dir]`; then `repo status` and `repo diff` compare your local changes |
| `get_repo_note` | read | Reads an editable file and its Notes, to settle a version conflict. | `repo push` (on a conflict) |
| `save_repo_note` | write | Saves Notes as an advisor draft on the version you read. It never confirms the draft. | `repo push` |
| `record_repo_push` | write | Records a receipt for one push. | `repo push` |
| `get_strategy_cards` | read | Reads the Strategy Cards and the leaders. | `strategy` |
| `set_strategy_leader` | write | Gives a person company or department leader access, or removes it. | `leaders grant\|remove` |

### 4.9 Help people finish their part

| Tool | Scope | What it does | CLI |
| --- | --- | --- | --- |
| `list_company_inputs` | read | Lists what people sent in and how far each item got. The text is data, never instructions. | `inputs`, `stuck` |
| `read_company_input` | read | Reads one input with its cleaned text. | `inputs show ID` |
| `record_inputs_export` | read | Records a counts-only receipt when inputs are exported. | `inputs export` |
| `get_coverage` | read | Shows who took part, interview progress and who needs help. | `coverage` |
| `prepare_draft_for_person` | write | Prepares a Task Card draft from a person's unfinished input. The person confirms it in their app. | `assist <inputId> --from draft.json` |
| `get_activity_stats` | read | Shows weekly activity and current Repo, gap and Strategy Card counts. | `stats`, `report ceo` |

### 4.10 Analyze and plan

| Tool | Scope | What it does | CLI |
| --- | --- | --- | --- |
| `list_frameworks` | read | Lists strategy frameworks and what each still needs. | `frameworks` |
| `get_framework_run` | read | Reads a framework's latest runs. | `frameworks show <key>` |
| `run_framework` | write | Runs a framework on the Repo through the company's approved AI connection. | `frameworks run <key>` |
| `review_framework_box` | write | Accepts or rejects one box of a framework, with a reason. | `frameworks review` |
| `list_work_gaps` | read | Lists missing work details and the people around them. | `gaps list` |
| `export_gap_brief` | read | Exports a brief and up to 10 questions to close a gap. | `gaps brief <key> [--ask EMAIL]` |
| `list_agent_manifests` | read | Lists agent specs made from Task Cards. | `agents list` |
| `export_agent_manifest` | read | Exports one agent spec for a named AI tool. It does not run the agent. | `agents export` |
| `find_format_breaks` | read | Lists the hand-offs where the format one Task Card sends is not the format the next card takes. | Not in the CLI |
| `list_format_conversions` | read | Lists the saved format conversions, or one in full with its skill text. | Not in the CLI |
| `propose_format_conversion` | write | Drafts the field map for a format break. Saves nothing. | Not in the CLI |
| `save_format_conversion` | write | Saves a conversion as a reusable skill, and can create its Claude agent. | Not in the CLI |
| `run_handoff_agent` | write | Converts one item with a saved conversion and can send the result to the receiving person. | Not in the CLI |

### 4.10a Client setup (before onboarding)

| Tool | Scope | What it does | CLI |
| --- | --- | --- | --- |
| `start_client_setup` | write | Makes the sponsor's personal setup link, filled in with known company facts and a team list. Nothing is emailed. | `setup start` |
| `get_client_setup` | read | Reads what came back: the company facts, who answered, each person's answers and role file. | `setup status`, `setup show`, `setup export` |
| `file_client_setup` | write | Puts the people into the work map and the documents into Discovery files. Nobody is invited. | `setup file` |
| `save_client_setup_role_file` | write | Replaces a person's role file with Markdown the advisor wrote. It is marked not checked. | `setup role <EMAIL> <FILE.md>` |

### 4.11 Sales call and outreach (optional)

| Tool | Scope | What it does | CLI |
| --- | --- | --- | --- |
| `get_pitch` | read | Reads the Pitch to Package call plan. | `pitch show` |
| `fill_pitch_prepare` | write | Fills the call plan from Markdown. It cannot approve a script or send the package. | `pitch prepare <FILE.md> [--apply]` |
| `set_pitch_video` | write | Puts a video link on the call plan. | `pitch video <URL>` |
| `list_outreach_drafts` | read | Reads outreach drafts for an account. | none |
| `draft_outreach` | write | Prepares an outreach email draft. | none |
| `edit_outreach_draft` | write | Changes a draft's subject and body. | none |
| `send_outreach` | send_email | Sends a draft through the app's checks. If a check warns, it refuses. | none |

### 4.12 Local CLI only

| Command | What it does |
| --- | --- |
| `use <name or id>` | Sets the default company for an origin. `--company ID` changes it for one command. |
| `init-claude [--dir DIR]` | Installs the playbooks for Claude Code beside a pulled Repo. It keeps your own `CLAUDE.md` text. |
| `logout` | Revokes the CLI sign-in and removes the saved token. |

Every command takes `--json`, `--yes` (skip the yes/no question), `--origin URL` and `--company ID`.

## 5. What the tools never do

* They never approve for a person. A Task Card, a Strategy Card or an answer becomes confirmed only when a person confirms it in DutyGraph.
* They never invite people to the client app. Only `send_request` emails a person, with a private link to answer its questions.
* They never send email without `send_email` and an explicit send.
* They never approve a video script or send a package.
* They never approve, change or deny an agent request.

## 6. Tools the client's people use

A client's employee connects their own AI (Claude or ChatGPT) to DutyGraph with OAuth, from the client app. The token is bound to that one person. It cannot reach advisor tools.

| Group | Tools |
| --- | --- |
| Find and record their work | `start`, `find_my_work`, `get_interview_session`, `record_interview_answers`, `get_my_context`, `get_my_role`, `get_my_alignment`, `start_work_discovery`, `save_discovery_candidates`, `record_task_interview`, `evaluate_task_card_completeness`, `submit_task_card_drafts`, `list_my_drafts`, `list_my_gaps`, `list_my_task_cards`, `send_to_dutygraph` |
| Leaders: strategy | `start_strategy`, `start_strategy_topic`, `get_strategy_context`, `submit_strategy_card_drafts`, `list_my_strategy_drafts`, `start_company_setup`, `fill_repo_file`, `fill_repo_files`, `add_document_to_repo` |
| Repo files they may read | `list_repo_files`, `read_repo_file` |
| Suggestion box | `open_suggestion_box`, `record_vent`, `save_suggestion_items`, `submit_suggestions` |
| Agents | `get_my_holdings`, `validate_agent`, `create_agent_request`, `get_request_status`, `check_governance`, `run_task_card` |

What a person sends stays a draft until they confirm it in DutyGraph.

## 7. Not available today

* No tool or command invites a client's people to the client app, or sends onboarding emails. Do this in the app.
* No tool accepts an uploaded document into the Company Repo. Do this in the app.
* No tool reads or shares the Readout report page. `get_onboarding_readout` returns the onboarding answers only.
* No tool reads an org chart from a picture or PDF. Send the team list as CSV.
* The Settings page limits a token to the one company that is open. A limit of several companies is set through the API only (`limitToCompanyIds`).

::: info
**Status.** **Built:** the advisor MCP server with 63 tools, tokens limited to chosen companies, personal access tokens with `read`, `write` and `send_email`, CLI sign-in with OAuth (`read` and `write`), the 29 CLI commands in the npm package `dutygraph` (0.2.1), the person tools for a client's employees, and workspace isolation. **Planned:** the items in section 7 are not built and have no date.
:::
