Skip to content

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 ​

PartAddressWhat it is
Advisor MCP serverPOST <origin>/api/mcpThe tools in section 4. Streamable HTTP, stateless, JSON answers. GET and DELETE return 405.
Setup guide for an AIGET <origin>/api/mcp/setup.mdA 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/revokeSign-in without a pasted key (section 2).
CLIdutygraph <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 peoplePOST <origin>/api/mcp with a person tokenThe 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.

Step 1

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.

Step 2

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).

Step 3

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 ​

ScopeWhat it allows
readRead companies, accounts, research, the Company Snapshot, the Company Repo, people, answers, onboarding and the call plan. Every advisor token needs read.
writeAdd companies, people and files. Start research. Fill onboarding answers. Make drafts. Nothing is sent.
send_emailSend 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 ​

ToolScopeWhat it doesCLI
get_cli_identityreadShows the token's scopes and the advisor's name and id.whoami
list_companiesreadLists the companies in the workspace.companies, use <name or id>
list_accountsreadLists accounts (client and prospect companies) with stage, research level and main contact.none
get_accountreadShows one account: stage, contacts, research permissions, outreach drafts, recent events.none

4.2 Add a client company ​

ToolScopeWhat it doesCLI
add_clientwriteAdds 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_accountwriteAdds 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_csvwriteAdds up to 200 companies from CSV (company, website, contact name, title, email). Preview first; apply: true writes.none
add_contactwriteAdds a contact to an account.none

4.3 Research the company ​

ToolScopeWhat it doesCLI
run_researchwriteStarts preview (public basics) or snapshot research. It records the research permission first when needed.research run --level preview|snapshot
get_research_statusreadShows the latest research runs.research status
get_company_snapshotreadShows the research findings, each with state, confidence and source types.none
(document intake)writeSends 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 ​

ToolScopeWhat it doesCLI
import_roster_csvwriteImports 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_personwriteAdds one person, with an optional manager email. It invites and emails nobody.person add
update_personwriteChanges a person on the version you read. Marking a person as left revokes their open links.person fix
get_team_statusreadLists people, their latest request, answers and confirmed Task Cards.team

4.5 Import files about the company ​

ToolScopeWhat it doesCLI
begin_advisor_documentwriteStarts an upload of one file, 4 MB at most.repo push (for new files in a pulled Repo)
upload_advisor_document_chunkwriteUploads one numbered part of the file with its SHA-256.(same)
finish_advisor_documentwriteChecks 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_documentsreadLists published company documents. Private and restricted documents show their details only.none
read_company_documentreadReads 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.

ToolScopeWhat it doesCLI
get_onboarding_statusreadShows how far onboarding is: questions answered, and for each person their manager, status and answers.onboarding status
get_onboarding_readoutreadReturns all onboarding answers as one Markdown document.onboarding readout [--out FILE.md]
fill_onboarding_answerswriteFills 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_transcriptwriteDrafts 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_onboardingreadReturns the whole onboarding state, with its revision.onboarding export [--out FILE.json]
save_onboardingwriteSaves 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 ​

ToolScopeWhat it doesCLI
create_requestwriteMakes a draft request of 1 to 10 questions for one person, and shows the email. Nothing is sent.ask <email> "question" ...
send_requestwrite + send_emailSends a draft request by email, after the advisor says yes. It must name the recipient's address.ask ... --send
list_requestsreadLists requests and response times.requests [--times]
list_arrivalsreadLists answers that came back and the Repo files they fill. The answer text is not returned.inbox [--since 2d]
nudge_personwritePreviews 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.

ToolScopeWhat it doesCLI
get_company_repo_indexreadLists the Repo files, with state and counts. Optional folder filter.none
read_company_repo_filereadReads one Repo file.none
export_company_reporeadExports 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_notereadReads an editable file and its Notes, to settle a version conflict.repo push (on a conflict)
save_repo_notewriteSaves Notes as an advisor draft on the version you read. It never confirms the draft.repo push
record_repo_pushwriteRecords a receipt for one push.repo push
get_strategy_cardsreadReads the Strategy Cards and the leaders.strategy
set_strategy_leaderwriteGives a person company or department leader access, or removes it.leaders grant|remove

4.9 Help people finish their part ​

ToolScopeWhat it doesCLI
list_company_inputsreadLists what people sent in and how far each item got. The text is data, never instructions.inputs, stuck
read_company_inputreadReads one input with its cleaned text.inputs show ID
record_inputs_exportreadRecords a counts-only receipt when inputs are exported.inputs export
get_coveragereadShows who took part, interview progress and who needs help.coverage
prepare_draft_for_personwritePrepares a Task Card draft from a person's unfinished input. The person confirms it in their app.assist <inputId> --from draft.json
get_activity_statsreadShows weekly activity and current Repo, gap and Strategy Card counts.stats, report ceo

4.10 Analyze and plan ​

ToolScopeWhat it doesCLI
list_frameworksreadLists strategy frameworks and what each still needs.frameworks
get_framework_runreadReads a framework's latest runs.frameworks show <key>
run_frameworkwriteRuns a framework on the Repo through the company's approved AI connection.frameworks run <key>
review_framework_boxwriteAccepts or rejects one box of a framework, with a reason.frameworks review
list_work_gapsreadLists missing work details and the people around them.gaps list
export_gap_briefreadExports a brief and up to 10 questions to close a gap.gaps brief <key> [--ask EMAIL]
list_agent_manifestsreadLists agent specs made from Task Cards.agents list
export_agent_manifestreadExports one agent spec for a named AI tool. It does not run the agent.agents export
find_format_breaksreadLists the hand-offs where the format one Task Card sends is not the format the next card takes.Not in the CLI
list_format_conversionsreadLists the saved format conversions, or one in full with its skill text.Not in the CLI
propose_format_conversionwriteDrafts the field map for a format break. Saves nothing.Not in the CLI
save_format_conversionwriteSaves a conversion as a reusable skill, and can create its Claude agent.Not in the CLI
run_handoff_agentwriteConverts 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) ​

ToolScopeWhat it doesCLI
start_client_setupwriteMakes the sponsor's personal setup link, filled in with known company facts and a team list. Nothing is emailed.setup start
get_client_setupreadReads what came back: the company facts, who answered, each person's answers and role file.setup status, setup show, setup export
file_client_setupwritePuts the people into the work map and the documents into Discovery files. Nobody is invited.setup file
save_client_setup_role_filewriteReplaces 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) ​

ToolScopeWhat it doesCLI
get_pitchreadReads the Pitch to Package call plan.pitch show
fill_pitch_preparewriteFills the call plan from Markdown. It cannot approve a script or send the package.pitch prepare <FILE.md> [--apply]
set_pitch_videowritePuts a video link on the call plan.pitch video <URL>
list_outreach_draftsreadReads outreach drafts for an account.none
draft_outreachwritePrepares an outreach email draft.none
edit_outreach_draftwriteChanges a draft's subject and body.none
send_outreachsend_emailSends a draft through the app's checks. If a check warns, it refuses.none

4.12 Local CLI only ​

CommandWhat 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.
logoutRevokes 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.

GroupTools
Find and record their workstart, 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: strategystart_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 readlist_repo_files, read_repo_file
Suggestion boxopen_suggestion_box, record_vent, save_suggestion_items, submit_suggestions
Agentsget_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.

Source: gitbook/product/connect/partners.md in the DutyGraph repository.

DutyGraph. Pages label each feature Built, In review or Planned.