MCP Tools¶

Context Teleport exposes 32 MCP tools that agents use to read and write project context. All tools return JSON strings. Agent identity is automatically detected via the MCP_CALLER environment variable (set during adapter registration).

Tools are organized into ten categories: Knowledge Management, Conventions, Skills, Decisions, State and History, Team Activity, Scoping, Git Sync, Conflict Resolution, and Markdown Navigation.

Knowledge Management¶

context_search¶

Search across all context files for a query string. Returns ranked results with file path, key, line number, matching text, and relevance score.

Returns:

[
  {
    "key": "architecture",
    "file": "knowledge/architecture.md",
    "line": 12,
    "text": "We use a microservices architecture with gRPC",
    "score": 0.95
  }
]

Example:

context_search(query="database migration")

context_add_knowledge¶

Add or update a knowledge entry. If the key already exists, the content is overwritten. The calling agent is automatically recorded as the author.

Returns:

{"status": "ok", "key": "architecture"}

Example:

context_add_knowledge(
    key="tech-stack",
    content="## Stack\n\n- Python 3.12\n- FastAPI\n- PostgreSQL 16",
    scope="public"
)

context_remove_knowledge¶

Remove a knowledge entry by key.

Returns:

{"status": "removed", "key": "tech-stack"}

Returns {"status": "not_found", "key": "..."} if the key does not exist.

context_get¶

Read any value from the context store by dotpath. Supports traversal into knowledge, decisions, state, manifest, and other top-level sections.

Dotpath examples:

• knowledge.architecture -- content of a specific knowledge entry
• decisions.1 -- decision with ID 1
• state -- full active state
• manifest.project.name -- project name from manifest

Returns:

The resolved value as JSON. Returns {"error": "No value at '<dotpath>'"} if the path does not resolve.

Example:

context_get(dotpath="manifest.project.name")

context_set¶

Set a value by dotpath. Writes to the underlying store file.

Returns:

{"status": "ok", "dotpath": "state.current_task"}

Returns {"status": "error", "error": "..."} if the path is invalid.

Example:

context_set(dotpath="state.current_task", value="Implementing auth middleware")

Conventions¶

Team conventions are shared behavioral rules (git workflow, environment constraints, communication style) that apply across all agents and tools.

context_add_convention¶

Add or update a team convention. If the key already exists, the content is overwritten. The calling agent is automatically recorded as the author.

Returns:

{"status": "ok", "key": "git"}

Example:

context_add_convention(
    key="git",
    content="Always use feature branches.\nCommit early, commit often.\nNo force-push to main.",
    scope="public"
)

context_get_convention¶

Read a specific convention by key.

Returns:

{"key": "git", "content": "Always use feature branches.\nCommit early, commit often.\nNo force-push to main."}

Returns {"error": "Convention 'nonexistent' not found"} if the key does not exist.

context_list_conventions¶

List all team conventions with their keys and scopes.

Returns:

[
  {
    "key": "git",
    "content": "Always use feature branches...",
    "scope": "public"
  },
  {
    "key": "environment",
    "content": "No sudo. Use venvs...",
    "scope": "public"
  }
]

context_rm_convention¶

Remove a team convention by key.

Returns:

{"status": "removed", "key": "git"}

Returns {"status": "not_found", "key": "..."} if the key does not exist.

Skills¶

context_add_skill¶

Add or update an agent skill. Constructs a SKILL.md file with YAML frontmatter from the provided name, description, and instructions. The calling agent is recorded automatically.

Returns:

{"status": "ok", "name": "deploy-staging"}

Example:

context_add_skill(
    name="run-tests",
    description="Execute the full test suite with coverage",
    instructions="## Steps\n\n1. Activate venv\n2. Run `pytest tests/ -v --cov`\n3. Check coverage is above 80%",
    scope="public"
)

context_remove_skill¶

Remove an agent skill by name.

Returns:

{"status": "removed", "name": "run-tests"}

Returns {"status": "not_found", "name": "..."} if the skill does not exist.

context_report_skill_usage¶

Record that a skill was used in the current session. Appends a usage event to the skill's .usage.ndjson sidecar file for tracking adoption and frequency.

Returns:

{"status": "ok", "event_id": "a1b2c3d4-..."}

Returns {"status": "error", "error": "..."} if the skill does not exist.

context_rate_skill¶

Rate a skill and optionally leave feedback. Appends to the skill's .feedback.ndjson sidecar file. Skills with an average rating below 3.0 and 2 or more ratings are automatically flagged as needing attention.

Returns:

{"status": "ok", "feedback_id": "e5f6g7h8-..."}

context_propose_skill_improvement¶

Create an improvement proposal for an existing skill. The proposal includes the full new SKILL.md content and a computed diff summary (via difflib). Proposals can be reviewed and resolved via CLI (context-teleport skill apply-proposal) or programmatically.

Returns:

{
  "status": "ok",
  "proposal_id": "i9j0k1l2-...",
  "diff_summary": "@@ -3,5 +3,7 @@\n ..."
}

context_list_skill_proposals¶

List skill improvement proposals with optional filters.

Returns:

[
  {
    "id": "i9j0k1l2-...",
    "skill_name": "deploy-staging",
    "agent": "claude-code",
    "status": "pending",
    "diff_summary": "@@ -3,5 +3,7 @@ ...",
    "rationale": "Add rollback step for failed deployments...",
    "created_at": "2025-05-10T14:30:00+00:00"
  }
]

Decisions¶

context_record_decision¶

Record an architectural decision in ADR (Architecture Decision Record) style. Decisions are auto-assigned sequential IDs.

Returns:

{"status": "ok", "id": 3, "title": "Use PostgreSQL for persistence"}

Example:

context_record_decision(
    title="Use PostgreSQL for persistence",
    context="Need ACID transactions and JSON support",
    decision="PostgreSQL 16 with pgvector extension",
    consequences="Team needs PostgreSQL expertise. Adds infra complexity."
)

State and History¶

context_update_state¶

Update the active session state. Partial updates are supported -- only provided fields are changed.

Returns:

{"status": "ok", "current_task": "Implementing auth middleware"}

Example:

context_update_state(
    current_task="Implementing auth middleware",
    blockers="Waiting for API spec, Redis not configured"
)

context_append_session¶

Append a session summary to the history log. Each summary gets a unique UUID.

Returns:

{"status": "ok", "session_id": "m3n4o5p6-..."}

Example:

context_append_session(
    agent="claude-code",
    summary="Set up database schema and migrations",
    knowledge_added="tech-stack, db-schema",
    decisions_added="3"
)

Team Activity¶

context_check_in¶

Check in to the team activity board. Records what you are currently working on so other team members can see your activity via onboarding or the context://activity resource.

Returns:

{"status": "ok", "member": "alice", "task": "Fixing DRC violations"}

Example:

context_check_in(task="Fixing DRC violations", issue_ref="#42")

context_check_out¶

Check out from the team activity board. Removes your activity entry so other team members know you are no longer actively working.

Returns:

{"status": "checked_out"}

Returns {"status": "not_found"} if no activity entry exists for the current member.

Scoping¶

context_get_scope¶

Get the current visibility scope of a knowledge entry, decision, convention, or skill.

Returns:

{"key": "architecture", "scope": "public"}

context_set_scope¶

Change the visibility scope of a knowledge entry, decision, convention, or skill.

Returns:

{"status": "ok", "key": "architecture", "scope": "private"}

Git Sync¶

context_sync_push¶

Commit and push context changes to the git remote. If no remote is configured, performs a local commit only.

Returns:

{"status": "pushed", "commit": "a1b2c3d"}

Or, if no remote is configured:

{"status": "committed", "commit": "a1b2c3d"}

context_sync_pull¶

Pull context changes from the git remote and merge. Supports three conflict resolution strategies.

Strategy options:

Returns (clean pull):

{"status": "pulled", "commit": "d4e5f6g"}

Returns (conflicts with agent strategy):

{
  "status": "conflicts",
  "conflict_id": "h7i8j9k0-...",
  "files": [".context-teleport/knowledge/architecture.md"]
}

Conflict Resolution¶

These five tools work together for interactive conflict resolution when using context_sync_pull(strategy="agent").

context_merge_status¶

Check if there are unresolved merge conflicts. Reads from the disk-persisted conflict state at .context-teleport/.pending_conflicts.json.

Returns (clean):

{"status": "clean"}

Returns (conflicts pending):

{
  "status": "conflicts",
  "conflict_id": "h7i8j9k0-...",
  "report": {
    "conflicts": [...],
    "auto_resolved": [...]
  }
}

context_conflict_detail¶

Get detailed conflict information for a single file. Returns the full content from all three sides (ours, theirs, base), a unified diff, and section-level analysis for markdown files.

Returns:

{
  "file_path": ".context-teleport/knowledge/architecture.md",
  "ours_content": "...",
  "theirs_content": "...",
  "base_content": "...",
  "diff": "--- .../architecture.md (ours)\n+++ .../architecture.md (theirs)\n...",
  "section_analysis": {
    "has_section_conflicts": false,
    "conflict_details": [],
    "auto_merged_content": "..."
  }
}

context_resolve_conflict¶

Resolve a single merge conflict by providing the final content. The resolution is persisted to disk. Call context_merge_finalize when all conflicts are resolved.

Returns:

{
  "status": "resolved",
  "file_path": ".context-teleport/knowledge/architecture.md",
  "remaining": 0
}

context_merge_finalize¶

Finalize the merge after resolving conflicts. Applies resolved content to files, falls back to ours for any still-unresolved files, and commits the merge. Clears the pending conflict state.

Returns:

{"status": "merged", "commit": "l1m2n3o4"}

context_merge_abort¶

Abort the pending merge and discard conflict state. The pending conflicts file is removed. The next context_sync_pull will re-detect conflicts.

Returns:

{"status": "aborted"}

Error Handling¶

All tools follow a consistent error pattern. When an operation fails, the returned JSON includes a status field set to "error" and an error field with a human-readable message:

{"status": "error", "error": "Knowledge entry 'nonexistent' not found"}

Common error conditions:

Markdown Navigation¶

Tools for navigating the structure of large markdown entries.

context_outline¶

Get the section outline (headings) of a knowledge, convention, or decision entry.

Returns: JSON array of headings with level, heading, and line fields.

context_get_section¶

Extract a specific section from an entry by heading name.

Returns: {"heading": "## Section", "content": "..."} or error if not found.

context_list_tables¶

List markdown tables found in an entry, with their surrounding heading context.

Returns: JSON array of tables with heading, line, content, and rows fields.

Agent Identity¶

The MCP server detects the calling agent via the MCP_CALLER environment variable. When an adapter registers Context Teleport as an MCP server, it sets this variable in the MCP configuration's env block. If MCP_CALLER is not set, the agent name defaults to mcp:unknown.

Agent identity is recorded on:

• Knowledge entries (author field)
• Decision records (author field)
• Skill entries (agent field)
• Session summaries (agent field)
• Usage events and feedback (agent field)
• Skill proposals (agent field)