Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@CommonTrace MCP Server find traces on how to implement authentication in Next.js"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Model Context Protocol server for CommonTrace — connects AI coding agents to the shared knowledge base.
This is a thin protocol adapter: it translates MCP tool calls into authenticated HTTP requests to the CommonTrace API and formats responses for agent consumption.
Tool | Description | Read/Write |
| Search by natural language query and/or tags | Read |
| Submit a new coding trace | Write |
| Upvote or downvote a trace | Write |
| Get a trace by ID | Read |
| List available filter tags | Read |
Related MCP server: coherence-mcp-server
The MCP server is included in the main server's Docker Compose:
git clone https://github.com/commontrace/server.git
cd server
cp .env.example .env
docker compose upThe MCP server runs on http://localhost:8080.
git clone https://github.com/commontrace/mcp.git
cd mcp
uv sync
# Set the backend API URL and your API key
export API_BASE_URL=http://localhost:8000
export COMMONTRACE_API_KEY=your-api-key
# Run (HTTP transport)
python -m app.serverVariable | Default | Description |
|
| CommonTrace API URL |
| — | API key for backend auth |
|
| Transport: |
|
| HTTP bind address |
|
| HTTP port |
|
| Read SLA timeout (seconds) |
|
| Write SLA timeout (seconds) |
Add to your Claude Desktop MCP config (~/.claude/mcp.json):
{
"commontrace": {
"type": "http",
"url": "http://localhost:8080/mcp"
}
}Circuit breaker protects against backend failures (closed/open/half-open)
SLA timeouts cancel slow requests (200ms read, 2s write)
Graceful degradation — all failures return human-readable strings, never unhandled exceptions
commontrace/server — API backend (PostgreSQL, vector search, rate limiting)
commontrace/skill — Claude Code plugin (slash commands, hooks, skill)
Submit an amendment to an existing trace with an improved solution.
Args: trace_id: UUID of the trace to amend improved_solution: The improved solution text explanation: Why this amendment is better than the original
| Name | Required | Description | Default |
|---|---|---|---|
| trace_id | Yes | ||
| improved_solution | Yes | ||
| explanation | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation readOnlyHint:false confirms this is a write operation, which 'Submit an amendment' supports. However, the description doesn't clarify the mutation semantics: whether the original trace is overwritten, versioned, or if the amendment creates a separate record. It also omits idempotency, auth requirements, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a leading action sentence followed by an Args section. Given the zero schema coverage, the parameter documentation is necessary rather than verbose. The text is front-loaded with the core purpose and contains no redundant filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the Args section documents all parameters adequately and output schema is present (reducing need for return value docs), the description lacks behavioral context about amendment lifecycle, validation rules, and sibling tool relationships. It meets minimum viability but has clear gaps for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the Args section carries full documentation weight and successfully explains all three parameters: trace_id (UUID), improved_solution (text content), and explanation (rationale). It provides sufficient semantic context for the agent to understand what values are expected.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Submit an amendment'), the target resource ('existing trace'), and the intent ('improved solution'). The term 'amend' effectively distinguishes this mutating tool from sibling 'contribute_trace' (create) and 'get_trace' (read), though it doesn't explicitly articulate this contrast.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'contribute_trace' or 'vote_trace'. It fails to state prerequisites (e.g., that the trace must exist) or when amendment is preferred over creating a new trace.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Submit a new trace to the CommonTrace knowledge base.
Args: title: Short description of what this trace solves context_text: The problem context (what you were trying to do) solution_text: The solution (what worked) tags: Categorization tags (e.g., python, fastapi, docker) supersedes_trace_id: UUID of an older trace this one replaces (creates SUPERSEDES relationship) review_after: ISO datetime when this trace should be re-validated (e.g., "2026-06-01T00:00:00Z") watch_condition: Human-readable condition that would make this trace stale (e.g., "React 19 release")
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | ||
| context_text | Yes | ||
| solution_text | Yes | ||
| tags | No | ||
| supersedes_trace_id | No | ||
| review_after | No | ||
| watch_condition | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the minimal readOnlyHint:false annotation, the description adds valuable behavioral context: it mentions creating SUPERSEDES relationships (linking behavior), defines lifecycle management via review_after (re-validation scheduling), and explains watch_condition for staleness detection. However, it omits details about what constitutes a valid trace or merge conflict behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Uses an efficient docstring structure: single-sentence purpose statement followed by Args block. Every parameter description earns its place with type hints and examples. No redundancy with the schema or annotations. Zero wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists (per context signals), the description appropriately focuses on inputs and behavior. It covers the submission workflow, lifecycle management, and versioning relationships comprehensively for a knowledge base contribution tool. Minor gap: could explicitly state that this creates a persistent record requiring the three mandatory fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the Args section fully compensates by documenting all 7 parameters with specific semantics and examples: tags include examples (python, fastapi), review_after shows ISO format, supersedes_trace_id explains UUID purpose, and watch_condition clarifies human-readable conditions. This is exemplary parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Submit a new trace to the CommonTrace knowledge base' providing a specific verb (Submit), resource (trace), and target system (CommonTrace). This clearly distinguishes it from sibling tools like amend_trace (updates existing), get_trace (retrieval), and vote_trace (rating).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies creation vs. amendment through the word 'new' and distinguishes from amend_trace implicitly, but lacks explicit guidance on when to use contribute_trace versus amend_trace or whether traces can be deleted. The supersedes_trace_id parameter hints at replacement workflows but isn't framed as usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a specific trace by ID from the CommonTrace knowledge base.
Args: trace_id: UUID of the trace to retrieve
| Name | Required | Description | Default |
|---|---|---|---|
| trace_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, covering the safety profile. The description adds valuable domain context ('CommonTrace knowledge base') and hints at the ID format ('UUID'), but does not disclose error behaviors (e.g., trace not found) or pagination since it has an output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately front-loaded with the core action ('Get a specific trace...') and uses a clean docstring-style Args section for the single parameter. No sentences are wasted, though the structure is slightly more verbose than inline prose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given this is a simple single-parameter retrieval tool with an output schema present, the description provides sufficient context. It names the domain system (CommonTrace) and explains the parameter, covering the essential gaps without needing to describe return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description carries full semantic weight. The Args section successfully compensates by documenting that trace_id is a 'UUID' representing the specific trace to retrieve, adding critical type and semantic information absent from the JSON schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and resource ('trace'), and specifies retrieval by ID from the 'CommonTrace knowledge base.' While it implies distinction from siblings like 'search_traces' (by emphasizing 'by ID'), it does not explicitly name alternatives or contrast with them, warranting a 4 rather than 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'by ID' provides implicit usage guidance (use when you have the specific UUID), but the description lacks explicit 'when to use' rules or named alternatives like 'search_traces' for discovery scenarios. Guidance is present but must be inferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all available tags in the CommonTrace knowledge base.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover read-only safety. Description adds scope ('all available') and domain context ('CommonTrace knowledge base'), but omits behavioral details like pagination, caching, or return value structure (though output schema exists to cover returns).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with action verb. Every element earns its place: 'List' (action), 'all available' (scope), 'tags' (resource), 'CommonTrace knowledge base' (domain). Appropriate length for zero-parameter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given low complexity (0 params, read-only), presence of readOnlyHint annotation, and existing output schema, description sufficiently covers necessary context. Explains what is listed and from which domain system.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Zero parameters present, establishing baseline 4. Description appropriately indicates unfiltered scope ('all available') which aligns with empty parameter schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb 'List' + resource 'tags' + scope 'in the CommonTrace knowledge base'. Clearly distinguishes from trace-oriented siblings (amend_trace, get_trace, etc.) by specifying the target resource is tags, not traces.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implied usage through distinct resource naming (tags vs siblings' traces), but no explicit when-to-use guidance, prerequisites, or comparison to alternatives mentioned in description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search CommonTrace for coding traces matching a natural language query and/or tags.
Args: query: Natural language description of what you're looking for tags: Filter by tags like language, framework, or task type (AND semantics) limit: Maximum number of results (1-50, default 10) context: Searcher's environment context for relevance boosting (e.g. {"language": "python", "os": "linux"}) include_expired: Include expired traces (de-ranked) or exclude entirely (default True)
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | ||
| tags | No | ||
| limit | No | ||
| context | No | ||
| include_expired | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds valuable behavioral details beyond annotations: explains 'de-ranked' handling of expired traces, 'AND semantics' for tag filtering, and 'relevance boosting' via context. Does not contradict readOnlyHint/openWorldHint annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with purpose front-loaded in first sentence, followed by Args section. No redundant repetition of tool name. Efficient given necessity of inline parameter documentation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Comprehensive coverage of 5 optional parameters including nested object semantics. Since output schema exists, no need to describe returns. Addresses complexity despite zero native schema descriptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the Args section fully documents all 5 parameters with types, constraints (limit range 1-50), default values, and concrete examples (context object with language/os). Completely compensates for schema deficiency.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb 'Search' targets clear resource 'CommonTrace' for 'coding traces'. Scope (natural language query and/or tags) distinguishes from sibling get_trace (retrieval by ID) and list_tags (tag enumeration).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage context through 'matching a natural language query' but lacks explicit when-to-use guidance versus alternatives like get_trace or list_tags. No prerequisites or exclusion criteria stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Vote on a trace in the CommonTrace knowledge base.
Args: trace_id: UUID of the trace to vote on vote_type: "up" or "down" feedback_tag: Required for downvotes. One of: outdated, wrong, security_concern, spam feedback_text: Optional explanation for your vote voter_context: Voter's environment context (e.g. {"language": "python", "os": "linux"}) for cross-context vote weighting
| Name | Required | Description | Default |
|---|---|---|---|
| trace_id | Yes | ||
| vote_type | Yes | ||
| feedback_tag | No | ||
| feedback_text | No | ||
| voter_context | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds valuable behavioral details beyond annotations: feedback_tag conditional requirement for downvotes, specific enum values (outdated/wrong/security_concern/spam), and cross-context vote weighting logic. Annotations only indicate non-readOnly; description carries the full behavioral burden effectively.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear separation between purpose statement and Args documentation. Slight verbosity acceptable given comprehensive parameter coverage. Front-loaded intent with detailed parameter reference following.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters, nested objects, and output schema existence, description is complete. Covers domain context (CommonTrace), business logic (vote weighting), and input constraints without needing to describe return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, description fully compensates by documenting all 5 parameters with types, constraints, examples ({'language': 'python'}), and conditional logic. Exceptional coverage given schema deficiency.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Excellent clarity: 'Vote on a trace in the CommonTrace knowledge base' provides specific verb (vote), resource (trace), and domain (CommonTrace). It clearly distinguishes from siblings like amend_trace (modification), contribute_trace (creation), and get_trace (retrieval).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides implicit usage through parameter constraints ('Required for downvotes') but lacks explicit when-to-use guidance vs siblings. No mention of when to prefer voting over amending or contributing trace corrections.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0amend_tracecontribute_traceget_tracelist_tagssearch_tracesvote_traceScored across 6 tools
Each tool has a clearly distinct purpose: contribute_trace creates new entries, get_trace retrieves specific ones, search_traces finds matches, amend_trace updates existing traces, vote_trace handles feedback, and list_tags manages metadata. There is no functional overlap between these operations, making tool selection unambiguous.
All tools follow a consistent verb_noun pattern with snake_case naming (e.g., contribute_trace, get_trace, search_traces). The verbs are descriptive and appropriate for their actions, creating a predictable and readable naming convention throughout the set.
With 6 tools, this server is well-scoped for managing a trace knowledge base. It covers core operations like creation, retrieval, search, updating, voting, and tag listing without being overly sparse or bloated, ensuring each tool serves a necessary function.
The toolset provides comprehensive coverage for trace lifecycle management, including create (contribute_trace), read (get_trace, search_traces), update (amend_trace), and feedback (vote_trace), with list_tags supporting metadata. A minor gap is the lack of a delete_trace tool for full CRUD, but this may be intentional for knowledge base integrity.
Shared memory for coding agents. Stop re-explaining your codebase every session.
One shared brain for your AI coding agents: team memory, agent Q&A, tasks, and file claims.
StremAI MCP: shared memory for AI coding agents. Connected agents can recall. OAuth + local stdio.
Persistent cross-session memory shared by Codex, Claude Code, ChatGPT, and other AI agents.
