MCP Tools
The server registered through MCP Integration provides these tools and resources to your agent. You do not invoke them directly; the agent selects one for the intent of your request.
Most are read tools. Write tools are open for documents and comments/replies only; every other record type (plans, completion reports, conventions, co-actions, post-mortems, code reviews) is written with the agentteams CLI.
Choose by intent
| Request intent | Tool to use |
|---|---|
| Exact count, filters, or full inventory | The matching agentteams_*_list. Each call returns one page, so use meta.total for the count and request every page from page=1 through meta.totalPages for the full inventory. |
| Topic or relevance discovery | agentteams_search. Check meta.truncatedByTokenBudget, and do not treat search results as an exact count or complete inventory. |
| Known ID or the full selected item | The matching agentteams_*_get. Prefixed IDs from list/search results or web links are normalized automatically. |
| A reference token of unknown type | agentteams_resolve. Pass the token as-is and it works out the type and fetches the record. When you already know the type, agentteams_*_get is cheaper. |
| Create, update, or delete a document | Call agentteams_guide_get("document") first, then the matching agentteams_document_* tool. |
| Create, update, or delete a comment | Call agentteams_guide_get("comment") first, then the matching agentteams_comment_* tool. |
| Any other write, download, or file | The agentteams CLI. Also use the CLI when MCP is disconnected or the required tool is unavailable. CLI commands do not call the MCP server as an internal transport. |
List results are metadata inventories and do not chain full-content requests. Fetch details only for the items you need.
Every search/list/get tool reads only the single project bound to the current MCP server or context client. Passing an ID from another project cannot change that scope.
What each profile exposes
Not every tool below is always visible. The tool profile chosen when the server was registered decides the exposed surface. See MCP integration for how to pick one and how the costs compare.
| Profile | Tools exposed |
|---|---|
full | All 33 tools on this page (the default) |
read | The 20 search/list/detail tools (no write tools) |
documents | agentteams_search, agentteams_document_*, agentteams_guide_get |
comments | agentteams_search, agentteams_comment_*, agentteams_guide_get |
minimal | agentteams_search, agentteams_plan_get, agentteams_document_get |
A tool outside the active profile is neither listed nor callable (Tool <name> not found). Resource templates are served regardless of profile.
minimal is the “search for it, then read only what you need in full” combination, so it has no list tools. When exact counts or complete inventories matter, use read or wider, or fall back to the agentteams CLI.
Search tool
| Tool | Role |
|---|---|
agentteams_search | Unified entity search across the project (semantic + keyword) |
The eight supported internal entity types are plans, completion reports, co-actions, post-mortems, conventions, documents, code reviews, and comments.
Reference resolution tool
| Tool | Role |
|---|---|
agentteams_resolve | Work out the type of one entity reference token and fetch its target |
Pass the reference exactly as it appears in a user message, plan body, or comment. The accepted forms are type:id, type:id:path, parent:child (codeReview:<reviewId>:<findingId>, plan:<planId>:<taskId>), a bare prefixed ID, an external marker (LINEAR_ISSUE, GITHUB_ISSUE, GITHUB_PR, GITLAB_ISSUE, GITLAB_MERGE_REQUEST, BITBUCKET_ISSUE, BITBUCKET_PR), and any of those wrapped in a [label](...) link.
The response kind tells the agent what to do next.
kind | Targets | What to do |
|---|---|---|
record | Plans, completion reports, post-mortems, co-actions, documents, conventions, code reviews, findings, plan tasks, Linear | Use the inline record. Body-bearing entities arrive here too, content included. |
localFile | convention:id:path that carries a path | Read the returned filePath yourself — or path when no filePath is given. This tool never reads local files. |
external | GITHUB_*, GITLAB_*, BITBUCKET_* | Open url or run suggestedCommand (gh / glab). |
- Unlike the
agentteams resolvecommand, no body is downloaded to disk: an MCP server has no working-directory contract, so the content is inlined in the response instead. - External references are never fetched for you, and
gh/glabare never executed — only the command string comes back. - A
convention:id:pathwhose path points outside the project’s.agentteams/directory — or that does not exist in the bound checkout — falls back to the server record. filePathis the reference’spathanchored to the local checkout this MCP session is bound to. When there is no such checkout, only the project-root-relativepathcomes back and the agent supplies its own base.- Because it dispatches to every entity type, this tool is exposed in the
fullprofile only.
Exact list tools
Every list tool returns the paginated data/meta response verbatim within the caller’s project permissions and visibility scope.
| Tool | Optional filters |
|---|---|
agentteams_plan_list | title, search, status, type, priority, assignedTo, createdByMemberId, dateFrom, dateTo, page, pageSize |
agentteams_report_list | search, planId, status, reviewStatus, createdByMemberId, dateFrom, dateTo, page, pageSize |
agentteams_coaction_list | search, status, visibility, source (defaults to MANUAL; AUTO_SESSION, or ALL for any source), createdByMemberId, dateFrom, dateTo, page, pageSize |
agentteams_postmortem_list | search, planId, status, createdByMemberId, dateFrom, dateTo, page, pageSize |
agentteams_document_list | q, createdByMemberId, tags, tagPrefix, untagged, favorite, visibility, archived, page, pageSize |
agentteams_convention_list | category, scope, archived, search, createdByMemberId, page, pageSize |
agentteams_codereview_list | search, status, targetType, dateFrom, dateTo, severity, sourcePlanId, sourceCompletionReportId, createdByMemberId, page, pageSize |
agentteams_comment_list | Plan: planId, type, order; finding: findingId, order; task: taskId, optional planId, order; document: documentId, order; shared page, pageSize |
agentteams_comment_reply_list | commentId (required), order, page, pageSize |
agentteams_comment_list requires exactly one known plan, code-review finding, plan-task, or document parent. There is no project-wide comment list.
Each listed comment carries replyCount, so replies are visible as a signal. Read reply bodies with agentteams_comment_reply_list. Replies are one level deep — a reply never has replies of its own.
The maximum pageSize is 100. Dates use YYYY-MM-DD; document untagged and favorite are booleans; tags is a non-empty string array.
Detail tools
| Tool | Role |
|---|---|
agentteams_plan_get | Full plan (body + structured tasks + progress + linked documents) |
agentteams_report_get | Full completion report |
agentteams_coaction_get | Full co-action |
agentteams_postmortem_get | Full post-mortem |
agentteams_document_get | Full document (body + linked plans) |
agentteams_convention_get | Full convention |
agentteams_codereview_get | Full code review and findings |
agentteams_comment_get | Full root comment |
agentteams_comment_reply_get | Full reply |
agentteams_codereview_finding_get | One finding plus its parent review header |
Use the existing public name agentteams_codereview_get; agentteams_code_review_get is not exposed. Comment IDs are raw and have no canonical prefix. See Entity Types & IDs for the other prefix rules.
A root comment ID and a reply ID are different values. agentteams_comment_get does not accept a reply ID, and agentteams_comment_reply_get does not accept a root comment ID. Passing the wrong kind is a not-found, never a silent read of the other record.
Write tools
| Tool | Role |
|---|---|
agentteams_guide_get | The guide body and guideHash to read before a write (document | comment) |
agentteams_document_create | Create a document |
agentteams_document_update | Update a document (only the fields you pass change) |
agentteams_document_delete | Delete a document (destructive) |
agentteams_plan_document_link | Link a document to a plan (an existing link finishes as alreadyLinked: true) |
agentteams_plan_document_unlink | Remove a plan–document link (the document is not deleted) |
agentteams_comment_create | Create a root comment (exactly one of planId | taskId | documentId | findingId) |
agentteams_comment_update | Edit a root comment (author only) |
agentteams_comment_delete | Delete a root comment (destructive — its replies go with it) |
agentteams_comment_reply_create | Reply to a root comment |
agentteams_comment_reply_update | Edit a reply (author only) |
agentteams_comment_reply_delete | Delete a reply (destructive) |
No write tool takes a projectId. They write only to the project the MCP server is bound to; another project is unreachable by construction.
Every write tool except the plan–document link tools accepts three optional contract fields. Omitting all three is valid and behaves exactly like a plain write.
guideHash— the hash returned byagentteams_guide_get. A stale local copy is rejected withGUIDE_OUTDATED, and the response names the hash and file the server expects. Recover withagentteams convention downloadand retry.idempotencyKey— a key that makes a retry safe. Repeating the same key with the same request replays the first result and does not send the notification twice. Reusing a key with a different request is rejected as a conflict. A key is remembered for 24 hours.expectedUpdatedAt— theupdatedAtyou last read. Pass it on update and delete so a concurrent edit is rejected instead of silently overwritten. Without it, a delete is unconditional.
Deletes are hard to undo. Confirm with the user before deleting anything you did not just create in this session.
Environments without write tools (a Direct BYOK desktop conversation, for example) receive the read tools only.
Resource templates
| Resource URI | Content |
|---|---|
agentteams://plan/{id} | Full plan (JSON) |
agentteams://document/{id} | Full document (JSON) |
agentteams://convention/{id} | Full convention (JSON) |
A resource returns exactly the same data as the detail tool for the same ID.
Usage examples
Exact count of open co-actions
With source omitted, the co-action list returns manual handoffs only (MANUAL). Pass source explicitly to include the session dumps runners record automatically.
- Call
agentteams_coaction_listwithstatus=OPENandpage=1. This counts manual handoffs only.- Add
source=AUTO_SESSIONto count automatic session dumps, orsource=ALLto count every source.
- Add
- Use
meta.totalas the count. - If you need every item, request
page=1..meta.totalPages.
Discover related records
- Search the topic with
agentteams_search. - Check
meta.truncatedByTokenBudget. - Fetch only the needed results with the matching detail tools.
Fetch a known ID
Skip search and pass the ID directly to the matching agentteams_*_get.
Target config file per scope
The files agentteams mcp install works with, per client.
| Client | User scope | Project scope |
|---|---|---|
| Claude Code | ~/.claude.json | delegates to claude mcp add |
| GitHub Copilot CLI | $COPILOT_HOME/mcp-config.json | .mcp.json |
| OpenCode | opencode.jsonc | opencode.json |
| Amp | settings.json | delegates to amp mcp add |
| Cursor CLI | ~/.cursor/mcp.json | .cursor/mcp.json |
| Kimi CLI | ~/.kimi-code/mcp.json | .kimi-code/mcp.json |
| Kiro CLI | ~/.kiro/settings/mcp.json | .kiro/settings/mcp.json |
| Antigravity | ~/.gemini/config/mcp_config.json | .agents/mcp_config.json |
| Grok Build | ~/.grok/config.toml | .grok/config.toml |
| Oh My Pi | ~/.omp/agent/mcp.json | .omp/mcp.json |
| Muse Code | ~/.config/muse/settings.json | Use --scope user |
| Codex | delegates to codex mcp add | config.toml (manual) |
- Codex, Copilot, Kiro and Grok Build user config roots honor
CODEX_HOME,COPILOT_HOME,KIRO_HOMEandGROK_HOME, respectively. The Oh My Pi user path honorsPI_CODING_AGENT_DIR. - Grok Build (both scopes) and Codex (user scope) are registered by delegating to
grok mcp addandcodex mcp add; both commands update an existing entry instead of refusing, so re-runninginstallis safe. The Codex project scope has no such command, so it stays a manual snippet. - Kiro CLI registers on
fulllike every other client, but registration conservatively narrows it to a union-free profile if the catalog ever contains a union at any input-schema depth; see MCP. - When the CLI writes a file itself, it preserves existing entries and comments. If the file cannot be parsed, nothing is written and the run is reported as failed.