MCP Tool Profiles¶

Authoritative reference for which MCP tools each agent kind can call, derived from the real gating code in tatara-cli (internal/mcp/profiles.go, server.go, tools.go) and the pod-injection code in tatara-operator (internal/agent/pod.go). This supersedes any per-kind tool tables in other docs if they disagree - re-derive from the source files listed under Where profiles live rather than trusting a second copy.

How gating works¶

• The operator (tatara-operator, internal/agent/pod.go) sets TATARA_TOOL_PROFILE in the agent pod's env, derived from the Task's spec.kind via toolProfileForKind. This is the only place the env var is actually assigned in the running platform.
• tatara mcp (the CLI, internal/cmd/mcp.go) reads TATARA_TOOL_PROFILE (or --tool-profile) and passes it into mcp.NewServer.
• tools/list is profile-invariant (Component 4a / G15): NewServer registers every tool, for every profile, unconditionally. This keeps the tools/list response byte-identical across all agent kinds so every pod shares one Anthropic prompt-cache prefix - a per-kind filtered list would fragment the cache (tools render first in cache order).
• Gating is enforced at call time instead, in the register() dispatch closure: before invoking a tool's handler, the server checks the resolved per-profile allow-set. A denied call never reaches the backend; it returns tool "<name>" is not permitted for profile "<profile>" and increments tool_calls_total{status="denied"}.
• Fail-open: TATARA_TOOL_PROFILE unset/empty -> allow == nil -> every registered tool is callable. This is the local-dev / no-profile path and logs a WARN.
• Fail-closed: a non-empty but unrecognized profile string resolves to the alwaysOn set only (4 tools) and logs a WARN. Profile gating is the sole authz boundary here - a typo must never silently grant the full surface.
• Identity note: every agent pod authenticates as the same OIDC client (tatara-agent). Authorization cannot key on caller identity, so it keys on tool profile plus env-scoped task/project context (TATARA_TASK, TATARA_PROJECT) instead.

Tool groups¶

72 tools are registered in total, from five Go functions in tatara-cli/internal/mcp/tools.go:

Memory (create_memory, get_memory, delete_memory, bulk_create_memories, get_ingest_job, query, describe, get_entity, search_entities, patch_entity, list_edges, create_edge, delete_edge) and code-graph (code_search, code_entity, code_neighbors, code_callers, code_callees, code_dependents, code_dependencies, code_file_imports, code_resource_graph, code_cross_repo, code_path, code_important, code_stats, code_ambiguous_edges, code_explain, code_related, code_hyperedges, code_communities, code_bridges) are unconditional: every named profile gets all 32 of them, unfiltered.

alwaysOn (all 8 named profiles, plus fail-closed unknown)¶

Chat (10) - chat flag profiles only¶

chat_create_room, chat_list_rooms, chat_get_room, chat_close_room, chat_add_participant, chat_list_participants, chat_remove_participant, chat_send_message, chat_poll_messages, chat_get_log.

Handoff (4) - continuity-carrying profiles only¶

Added after the tool surface was last widely documented; not yet reflected everywhere else in the docs tree.

Per-kind profile table¶

toolProfileForKind maps a Task kind to a profile name (note triageIssue -> triage and issueLifecycle -> lifecycle; the CRD kind and the MCP profile name diverge for these two).

Total = 32 (memory + code-graph, unconditional) + chat (0 or 10) + handoff (0, 3, or 4) + profile-specific operator tools + 4 (alwaysOn). healthCheck shares Kind and profile with brainstorm per the operator ("same goal, same tools").

lifecycle is the largest named profile (63 tools) because it is a single long-lived pod spanning Triage -> Conversation -> Implement -> MRCI -> Merge; per-lifecycle-state gating is infeasible without restarting the MCP server, so it gets the union of every other profile's operator tools.

refine's 6-tool operator surface is deliberately deny-by-default: it omits create_issue (issue creation is an escalation vector) and every SCM-mutation or lifecycle-escalation tool. Historical notes elsewhere describe refine as "~42 tools" - that count predates the handoff group being added (32 + 6 + 4 = 42); with handoff + delete_handoff now included, refine is 46.

project_list and create_issue are registered (OperatorTools()) but not granted to any named profile - they are reachable only in fail-open mode (empty TATARA_TOOL_PROFILE, e.g. local dev without the operator injecting a profile).

Operator tool matrix¶

All 25 OperatorTools() (project_get, repo_list, task_get are the alwaysOn 3 of these and are omitted below since every profile has them).

By category¶

* alwaysOn - present in every profile including fail-closed unknown.

Notable fields¶

• change_summary requires change_significance (major | minor | patch) as of the semver push-CD cutover - the tool call is rejected server-side if omitted or not one of the three enum values. This is what drives the auto-merge -> semver tag -> tatara-helmfile cascade; humans set the equivalent via a semver:<level> PR label.
• edit_issue patches only title and body. Labels are intentionally not editable through this tool - issue labels drive the lifecycle state machine and stay operator/maintainer-controlled, so no profile (including refine, the groomer) can set them.
• decline_implementation / already_done / skip_research all require a non-empty reason; a silent finish with no PR and no outcome call is rejected as an unexplained refusal.

Where profiles live¶

How to change a kind's tool surface¶

1. To change which tools a profile grants: edit the profiles map (or a group* slice) in tatara-cli/internal/mcp/profiles.go.
2. To add a new tool: add it to the relevant *Tools() function in tatara-cli/internal/mcp/tools.go, then add its name to the profile(s) that should get it in profiles.go.
3. To remap which profile a Task kind gets: edit toolProfileForKind in tatara-operator/internal/agent/pod.go (this is the one that matters at runtime; keep the tatara-cli copy in sync since its test asserts the same mapping contract).
4. Both repos deploy via the standard semver push-CD path: merge to main with the required change_significance on change_summary (or a semver:<level> PR label for a human change) -> CI builds and tags -> tatara-helmfile auto-applies the new image/chart pin to the cluster. Never hand-edit a deploy pin; a tatara-cli change also needs the tatara-claude-code-wrapper image's TATARA_CLI_VERSION bumped forward before agent pods pick it up.