MCP Tools Reference

OpRelay exposes 17 MCP tools organized around collaborative agent work. All tools use project_key scoping and require auth_token when the server has MCP_AUTH_TOKEN set.

Shared State Tools

get_context

Bounded retrieval of facts, decisions, and runs for a project. Use at session start for baton-pass.

{
  "project_key": "my-project",
  "agent": "claude-code",
  "max_facts": 50,
  "max_decisions": 20,
  "max_runs": 10,
  "auth_token": "TOKEN"
}

get_fact

Exact fact lookup by category + key.

{
  "project_key": "my-project",
  "category": "infra",
  "key": "database",
  "auth_token": "TOKEN"
}

upsert_fact

Write structured operational state, scoped by project.

{
  "project_key": "my-project",
  "category": "infra",
  "key": "database",
  "value_json": "{\"engine\": \"postgres\", \"version\": \"16\"}",
  "source": "my-agent",
  "confidence": 1.0,
  "tags": ["infra", "database"],
  "auth_token": "TOKEN"
}

Field	Type	Required	Notes
project_key	string	yes	Scoping key
category	string	yes	Dot-separated: infra, stack.server
key	string	yes	Unique within project+category
value_json	any	yes	String or object — stored as-is
source	string	no	Defaults to "manual"
confidence	number	no	Float 0-1, defaults to 1.0
tags	string[]	no	Defaults to []
auth_token	string	yes*	Required when MCP_AUTH_TOKEN is set

upsert_decision

Record an engineering decision with rationale.

{
  "project_key": "my-project",
  "decision_key": "use_advisory_locks",
  "summary": "Use Postgres advisory locks for task claiming",
  "rationale": "Avoids deadlocks, supports timeout-based contention",
  "status": "accepted",
  "tags": ["architecture", "core"],
  "auth_token": "TOKEN"
}

Field	Type	Required	Notes
project_key	string	yes
decision_key	string	yes	Unique within project
summary	string	yes	Short description
rationale	string	no	Why this decision was made
status	string	no	draft, accepted, superseded, rejected
source_ticket	string	no	e.g., OPR-1
agent	string	no	Who made the decision
tags	string[]	no
auth_token	string	yes*

record_run

Append an immutable audit trail entry for an agent execution.

{
  "project_key": "my-project",
  "agent": "claude-code",
  "ticket": "OPR-1",
  "summary": "Implemented dashboard MVP",
  "meta_json": {
    "status": "success",
    "files_touched": ["dashboard/", "server/src/apiRoutes.ts"],
    "git": {
      "repo": "oprelay/oprelay",
      "branch": "codex/example",
      "head_sha": "abc1234",
      "pr_number": 42
    }
  },
  "auth_token": "TOKEN"
}

Field	Type	Required	Notes
project_key	string	yes
agent	string	yes	Agent identifier
ticket	string	no	Linear/Jira ticket
summary	string	yes	What was done
meta_json	object	no	Structured run metadata
auth_token	string	yes*

list_projects / list_categories / list_fact_keys

Discovery tools — no write side effects. All require auth_token. list_categories and list_fact_keys also require project_key.

health

Database connectivity check. No auth required.

Coordination Tools

core_register_agent

Agent self-registration with capabilities.

{
  "name": "claude-code",
  "capabilities": ["code", "review", "test"],
  "auth_token": "TOKEN"
}

core_start_run / core_end_run

Run lifecycle with structured outcomes. core_start_run returns a run_id used for all subsequent coordination in that session. core_end_run records the outcome, token usage, and files touched.

core_create_task

Create coordinated work items with optional dependencies.

{
  "project_key": "my-project",
  "title": "Add user authentication",
  "description": "Implement OAuth2 flow",
  "priority": "high",
  "depends_on": [],
  "auth_token": "TOKEN"
}

core_claim_task

Claim a task with advisory-lock contention safety. Only one agent can claim a task at a time.

core_transition_task

Append status transitions: pending → in_progress → done / failed / blocked.

core_update_task

Update task metadata, assignment, and routing.

core_list_tasks

Query tasks with filtering by status, assignee, project, and title search.

core_record_failure

Record structured failure events with context for debugging and recovery.

Common Mistakes

confidence is a number, not a string

BAD:  "confidence": "confirmed"     → validation error
BAD:  "confidence": "high"          → validation error
GOOD: "confidence": 1.0
GOOD: (omit it — defaults to 1.0)

auth_token goes in arguments AND the header

The Authorization: Bearer header authenticates the HTTP transport. Each tool call also requires auth_token in its arguments. Both are needed.

StreamableHTTP requires a session lifecycle

You cannot fire one-shot HTTP requests. The protocol requires:

1. initialize → capture Mcp-Session-Id from response headers
2. notifications/initialized → with session ID header
3. Tool calls → with session ID header

Accept header must include both content types

BAD:  Accept: application/json
GOOD: Accept: application/json, text/event-stream