What can you do with this server?

This MCP server provides issue tracking and knowledge retrieval capabilities through tools exposed to AI clients. * Ping the server to verify it is running. * List all issues from the REST API. * Get a single issue by its ID. * Create new issues (with title, description, optional status and priority). * Update existing issues (partial updates to title, description, status, or priority). * Delete issues by ID. * Search troubleshooting knowledge using vector similarity (RAG-based semantic search). * Write operations (create, update, delete) require human approval when invoked via the AI agent, while read and search tools run directly.

How do I use MCP Issue Tracker?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@MCP Issue Tracker show me all issues" 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.

MCP Issue Tracker

by jgonzalezar

Overview Schema Source Related Servers Discussions Admin

Python

Local

MCP Issue Tracker

A small issue-tracking backend built with FastAPI and SQLAlchemy, exposed to AI clients through a Model Context Protocol (MCP) server and integrated with an OpenAI agent.

The project demonstrates how an MCP server can act as an integration layer on top of an existing REST API instead of accessing the database directly. It also includes a small Retrieval-Augmented Generation (RAG) pipeline using OpenAI embeddings and Chroma, allowing the agent to retrieve troubleshooting knowledge before answering technical questions.

Write operations remain protected by explicit human approval.

Architecture

                              User
                                |
                                | Natural language
                                v
                       +------------------+
                       |   OpenAI Agent   |
                       |   Agents SDK     |
                       +--------+---------+
                                |
                                | MCP tool selection
                                v
                       +------------------+
                       |    MCP Server    |
                       |      Python      |
                       +----+---------+---+
                            |         |
          issue CRUD tools  |         | search_knowledge
                            |         |
                            v         v
                  +----------------+  +-------------------+
                  | Human approval |  |  RAG Retrieval    |
                  | for write ops  |  |                   |
                  +-------+--------+  | query embedding   |
                          |           |        |          |
                          v           |        v          |
                    FastAPI REST API  |     Chroma        |
                          |           |        |          |
                          |           | relevant chunks  |
                          |           +--------+----------+
                          |                    |
                          v                    |
                  SQLAlchemy / SQLite          |
                                               |
                                               v
                                      grounded answer

The issue-management tools communicate with the FastAPI REST API over HTTP using HTTPX.

The search_knowledge tool uses OpenAI embeddings and a local persistent Chroma collection. Knowledge documents are indexed separately, then retrieved at query time using cosine-distance vector search.

A simpler MCP client is also included for direct MCP tool discovery and invocation without an AI model.

Related MCP server: JIRA MCP Server

Tech Stack

Python 3.12+
FastAPI
Pydantic
SQLAlchemy 2
SQLite
Model Context Protocol Python SDK
OpenAI Agents SDK
OpenAI Embeddings API
Chroma
HTTPX
pytest
uv

Features

REST API for issue management
Persistent storage with SQLite and SQLAlchemy
Request and response validation with Pydantic
Automatic OpenAPI documentation with FastAPI
MCP server exposing issue operations as tools
Asynchronous HTTP communication between the MCP server and REST API
HTTP and connection error handling translated into MCP tool errors
OpenAI agent capable of selecting MCP tools from natural-language requests
Multi-turn conversational context within an interactive session
Human-in-the-loop approval for MCP write operations
RAG-based troubleshooting knowledge retrieval
OpenAI embeddings for semantic search
Persistent vector storage with Chroma
Document chunking before indexing
Cosine-distance retrieval
Relevance threshold to reject unrelated results
Strict grounding for troubleshooting answers
Source attribution in grounded responses
Automated API integration tests
Automated AI approval workflow tests
Automated RAG retrieval tests
Isolated in-memory SQLite database for API tests

Issue Model

An issue contains:

{
  "id": 1,
  "title": "Login fails",
  "description": "Login fails after session expiration.",
  "status": "open",
  "priority": "high"
}

Supported statuses:

open
in_progress
closed

Supported priorities:

low
medium
high

REST API

Method	Endpoint	Description
`GET`	`/health`	API health check
`GET`	`/issues`	List all issues
`GET`	`/issues/{id}`	Retrieve an issue
`POST`	`/issues`	Create an issue
`PATCH`	`/issues/{id}`	Partially update an issue
`DELETE`	`/issues/{id}`	Delete an issue

FastAPI automatically provides interactive API documentation at:

http://127.0.0.1:8000/docs

MCP Tools

The MCP server exposes the following tools:

Tool	Description	Approval
`ping`	Check whether the MCP server is running	No
`list_issues`	Retrieve all issues	No
`get_issue`	Retrieve an issue by ID	No
`create_issue`	Create a new issue	Required in AI client
`update_issue`	Partially update an issue	Required in AI client
`delete_issue`	Delete an issue	Required in AI client
`search_knowledge`	Search troubleshooting knowledge using vector similarity	No

The MCP server communicates with the REST API using HTTPX instead of accessing SQLite directly.

This keeps the REST API reusable by clients that do not use MCP and prevents the MCP layer from depending on database sessions or persistence details.

The RAG path is separate: search_knowledge calls the knowledge-base layer, which embeds the query and searches the persistent Chroma collection.

AI Agent

The project includes an interactive AI client built with the OpenAI Agents SDK.

The agent receives natural-language requests, discovers the available MCP tools, and decides which tool to invoke.

Example write operation:

You: Create a high priority issue titled "Login problem"
     with the description "Users cannot log in."

--- Approval required ---
Tool: create_issue
Arguments: {"title":"Login problem","description":"Users cannot log in.","priority":"high"}
Approve? [y/N]: y

Assistant: Created issue #2: Login problem

Read operations can execute directly, while write operations require explicit user approval.

Human-in-the-loop write protection

The following tools are considered write operations:

create_issue
update_issue
delete_issue

If the agent attempts to call one of them, execution is interrupted before the MCP tool runs.

The application then asks the user to approve or reject the operation:

LLM selects write tool
        |
        v
Run is interrupted
        |
        v
User sees tool + arguments
        |
   +----+----+
   |         |
 approve    reject
   |         |
   v         v
execute     do not execute

This allows the model to propose changes without giving it unrestricted authority to modify application data.

RAG Knowledge Retrieval

The project includes a small local troubleshooting knowledge base stored as Markdown files.

Example sources:

knowledge/
├── authentication.md
├── database.md
└── deployment.md

The RAG flow has two separate phases.

Ingestion

knowledge documents
        |
        v
     chunking
        |
        v
OpenAI embeddings
        |
        v
      Chroma

Each chunk is stored with metadata such as:

{
  "source": "database.md",
  "chunk_index": 0
}

The Chroma collection is persisted locally under .chroma/, which is ignored by Git because it is generated from the source documents.

Retrieval

At query time:

user question
      |
      v
query embedding
      |
      v
cosine-distance search
      |
      v
most relevant chunk
      |
      v
MCP search_knowledge result
      |
      v
OpenAI agent
      |
      v
grounded answer + source

Only the query is embedded at search time. Document embeddings are generated during indexing and reused from the persistent vector store.

Grounding and abstention

The agent is instructed to answer troubleshooting questions only using information returned by search_knowledge.

If no retrieved chunk passes the configured relevance threshold, the agent must abstain instead of answering from its own general knowledge.

Example:

You: How do I center a div with CSS?

Assistant: The knowledge base does not contain enough relevant
information to answer how to center a div with CSS.

This avoids treating the nearest vector as automatically relevant. Nearest-neighbor search always returns the closest item, even when the corpus contains no genuinely useful document.

For grounded answers, the agent also identifies the source document when possible.

Getting Started

1. Clone the repository

git clone https://github.com/jgonzalezar/mcp-issue-tracker.git
cd mcp-issue-tracker

2. Install dependencies

The project uses uv for Python and dependency management.

uv sync

3. Configure the OpenAI API key

The AI client and RAG embedding workflow require an OpenAI API key.

PowerShell:

$env:OPENAI_API_KEY="your-api-key"

Do not commit API keys to the repository.

4. Start the REST API

uv run uvicorn mcp_issue_tracker.api:app --reload

The API will be available at:

http://127.0.0.1:8000

5. Index the knowledge base

Before using RAG search, index the Markdown documents:

uv run python -m mcp_issue_tracker.knowledge_base index

This creates or updates the persistent Chroma collection.

The generated .chroma/ directory is intentionally not committed to Git.

You can test retrieval directly:

uv run python -m mcp_issue_tracker.knowledge_base search "How should I investigate a slow SQL query?"

6. Run the basic MCP demo client

Keep the FastAPI server running and open another terminal:

uv run python -m mcp_issue_tracker.mcp_client

The demo client starts the MCP server as a subprocess using the stdio transport and discovers the available tools.

7. Run the AI client

uv run python -m mcp_issue_tracker.ai_client

Example session:

Issue Tracker AI
Type 'exit' to quit.

You: How should I investigate a slow SQL query?

Assistant:
- Check database query execution times.
- Use EXPLAIN or EXPLAIN ANALYZE.
- Look for sequential scans on large tables.
- Check whether filters and joins use appropriate indexes.
- Verify database connection-pool usage.

Source: database.md

You: Create a high priority issue called "Slow database queries".

--- Approval required ---
Tool: create_issue
Arguments: {...}
Approve? [y/N]:

The conversation remains contextual during the current process, allowing follow-up prompts such as:

What issue did you just create?
Change its status to in progress.
Based on our knowledge base, how should I investigate it?

MCP Server

The MCP server can also be started directly:

uv run python -m mcp_issue_tracker.mcp_server

With the default stdio transport, the process waits for an MCP client to communicate through standard input and output.

The AI client launches the MCP server as a subprocess and passes the required environment variables explicitly, including the OpenAI API key needed by the RAG embedding flow.

Configuration

By default, the MCP server connects to:

http://127.0.0.1:8000

A different REST API URL can be provided through:

ISSUE_TRACKER_API_URL

PowerShell example:

$env:ISSUE_TRACKER_API_URL="http://localhost:9000"

The OpenAI integration uses:

OPENAI_API_KEY

The API key should be provided through the environment and must not be committed to the repository.

Testing

Run the complete automated test suite with:

uv run pytest -v

The current suite contains 10 tests covering the REST API, AI approval workflow, and RAG retrieval behavior.

API tests

The API tests use a separate in-memory SQLite database so that test execution does not modify the development database.

They cover:

complete issue CRUD lifecycle
request validation
invalid priority handling
404 Not Found behavior

AI approval tests

The AI approval tests do not call the real OpenAI API.

pytest monkeypatching is used to replace the OpenAI Runner and user input with deterministic test doubles.

They cover:

the set of write tools that require approval
successful approval of an interrupted write operation
rejection of a write operation
resumption of an interrupted agent run after the approval decision

RAG tests

The RAG tests mock both the embedding and vector-store boundaries.

They cover:

paragraph-based chunking
successful retrieval of a relevant result
filtering of results above the relevance threshold
failure behavior when the knowledge base is empty

These tests do not require a live OpenAI API call or a real Chroma database.

Design Decisions

Separate REST and MCP layers

The MCP server does not access the relational database directly. It consumes the FastAPI REST API over HTTP.

This introduces an additional network dependency, but keeps responsibilities separated and allows the REST API to be reused independently of MCP.

The MCP server therefore acts as an adapter between AI/MCP clients and the existing application API.

Separate ingestion and retrieval

Knowledge documents are embedded during a dedicated indexing phase.

At query time, the application embeds only the user query and searches against already persisted vectors.

This avoids recalculating document embeddings for every request.

Pydantic models vs. SQLAlchemy entities

Pydantic models define the external API contract and perform validation.

SQLAlchemy entities represent the persistence layer and database schema.

Keeping them separate prevents the database representation from becoming tightly coupled to the HTTP API.

Synchronous database access

The project uses synchronous SQLAlchemy sessions.

FastAPI supports synchronous route handlers and can execute them appropriately without requiring the database layer to be converted to asynchronous code.

The MCP server uses asynchronous HTTPX calls because communication with the REST API is I/O-bound.

Lazy initialization for RAG dependencies

Chroma and the OpenAI client are initialized lazily rather than at module import time.

This avoids delaying the MCP server startup and keeps the initial stdio handshake responsive.

The synchronous RAG search path is executed through asyncio.to_thread() so that expensive imports and blocking operations do not block the MCP event loop.

Human approval for AI write operations

Read tools can be used directly by the agent because they do not modify application state.

Before create_issue, update_issue, or delete_issue is executed, the agent run is interrupted and the user must explicitly approve the proposed tool invocation.

This keeps the language model useful for deciding what action to take while keeping the final authorization decision with the user.

Relevance threshold

Vector search always returns the closest result, even when the closest result is not actually relevant.

The retrieval layer therefore applies a cosine-distance threshold and discards results that are too distant from the query.

If no result passes the threshold, the agent is instructed to abstain.

The threshold used in this small prototype is intentionally empirical and would need calibration against representative queries in a production system.

Grounded troubleshooting answers

For troubleshooting and technical guidance, the agent is instructed to answer only from retrieved knowledge.

This prevents the model from silently mixing its own general knowledge with the project's knowledge base and makes source attribution possible.

SQLite and local Chroma

SQLite and a local persistent Chroma collection were chosen to keep the project lightweight and easy to run without external infrastructure.

For a production system, these could be replaced with services such as PostgreSQL and a production-oriented vector-search solution depending on scale and architecture.

Error Handling

FastAPI returns standard HTTP responses such as:

201 Created
204 No Content
404 Not Found
422 Unprocessable Entity

The MCP layer translates REST and network failures into MCP ToolError responses.

For example:

Issue Tracker API returned HTTP 404: Issue not found

or:

Issue Tracker API is unavailable.

The RAG MCP tool also converts retrieval failures into MCP tool errors.

This keeps transport failures, REST API errors, and knowledge-retrieval failures explicit instead of silently treating them as successful results.

Project Structure

mcp-issue-tracker/
├── knowledge/
│   ├── authentication.md
│   ├── database.md
│   └── deployment.md
│
├── src/
│   └── mcp_issue_tracker/
│       ├── __init__.py
│       ├── ai_client.py
│       ├── api.py
│       ├── database.py
│       ├── db_models.py
│       ├── knowledge_base.py
│       ├── models.py
│       ├── mcp_client.py
│       └── mcp_server.py
│
├── tests/
│   ├── test_ai_client.py
│   ├── test_api.py
│   └── test_knowledge_base.py
│
├── .gitignore
├── .python-version
├── pyproject.toml
├── uv.lock
└── README.md

The generated .chroma/ directory is excluded from version control.

Possible Improvements

Possible next steps for a production-oriented version include:

PostgreSQL instead of SQLite
PostgreSQL with pgvector or a managed vector database
Alembic database migrations
Authentication and authorization
API keys or OAuth for MCP access
More granular authorization policies for AI actions
Persistent conversation storage
Token-based chunking and chunk overlap
Larger evaluation dataset for tuning the relevance threshold
Retrieval evaluation metrics
Hybrid keyword + vector search
Reranking
Docker support
CI/CD with GitHub Actions
MCP Streamable HTTP transport
Remote MCP deployment
Additional MCP resources and prompts
Pagination and filtering
Structured logging and observability
Tracing of AI tool calls, retrievals, and approvals
More extensive automated testing

Purpose

This project was built as a hands-on exercise to explore Python backend development, FastAPI, SQLAlchemy, REST APIs, asynchronous HTTP communication, automated testing, the Model Context Protocol, AI tool calling, conversational agents, human-in-the-loop approval workflows, embeddings, vector search, and Retrieval-Augmented Generation.

Available Tools

6 tools

create_issueD

Create new issue

ParametersJSON Schema

Name	Required	Default
`title`	Yes
`status`	No	open
`priority`	No	medium
`description`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

D1.5/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden, yet it discloses nothing: no permission requirements, no side effects, no note about required fields or what the creation returns. 'Create new issue' says only what the name already says.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The text is short but that brevity reflects under-specification rather than efficiency. There is a single fragment with no structure and nothing front-loaded because nothing of substance is present.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a four-parameter mutation tool with no annotations and 0% schema description coverage, the description is completely inadequate. Even with an output schema present, the agent lacks the input semantics, defaults, and authorization context needed to call this correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% across four parameters, including enum definitions (IssueStatus, IssuePriority) with no descriptions and required fields (title, description) with no explanation. The description compensates for none of this, adding zero parameter meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose2/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Create new issue' merely restates the tool name create_issue as a sentence. It names a verb and resource but adds no distinguishing detail beyond what the identifier already conveys, and gives no hint of scope or content relative to siblings like update_issue or delete_issue.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives. An agent gets no indication of when creating an issue is appropriate versus updating or listing one, so the description provides no usage direction at all.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

delete_issueC

Delete issue by its ID

ParametersJSON Schema

Name	Required	Description	Default
`issue_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full behavioral burden, and it discloses almost nothing. For a destructive tool it fails to say whether deletion is permanent, whether it cascades (comments, sub-issues), or what authorization is required.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single short sentence, front-loaded with the verb and resource, with no wasted words. It is arguably too terse, but nothing is redundant.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists so return values need not be explained. However, for an irreversible mutation with no annotations and one undocumented parameter, the description leaves out critical context an agent needs before invoking it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but there is only one self-evident parameter (issue_id, integer). The phrase 'by its ID' merely restates the parameter name, adding no format, range, or validity detail beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Delete) and resource (issue) plus the lookup key. It is distinguishable from siblings like get_issue/update_issue by the destructive verb, though it does nothing explicit to contrast itself with them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this vs update_issue or list_issues, and no mention of prerequisites such as permissions or confirming the deletion. The agent must infer everything from the name.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_issueC

Return one issue by its ID.

ParametersJSON Schema

Name	Required	Description	Default
`issue_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only implies a read operation through the verb 'Return' but does not state that it is read-only, whether it requires permissions, or what happens if the issue ID does not exist.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, front-loaded sentence that is appropriately sized for a simple retrieval tool. It contains no filler or redundant phrasing.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The presence of an output schema means return values need not be explained, which reduces the description's burden. However, with no annotations and zero schema description coverage, the description still omits usage guidance and behavioral context that an agent would need to call the tool confidently.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate for the undocumented parameter. 'By its ID' merely restates the parameter name without adding format, range, or validity details beyond what the schema already shows.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Return') and resource ('issue') with a clear retrieval scope ('by its ID'). It is clear what the tool does, but it does not explicitly differentiate itself from siblings like list_issues or create_issue, which is why it falls short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description offers no when-to-use guidance or mention of alternatives. It does not say to use this tool instead of list_issues when a single issue is needed, nor does it describe any preconditions such as requiring a valid ID.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_issuesB

Return all issues from the Issue tracker API.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

B3.1/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden, yet it only says 'all issues' and discloses nothing about pagination, result caps, sorting, rate limits, or auth. 'from the Issue tracker API' is filler rather than behavioral context, so this is thin for a bare-annotations tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no waste. The trailing 'from the Issue tracker API' adds little, but the sentence is still tight and appropriately sized.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Zero parameters and an existing output schema remove the need to explain inputs or return shape, so the description is nearly complete. However, a listing tool that claims to return 'all' issues should hint at pagination or result limits, which is absent with no annotations to compensate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so the baseline is 4. The schema is empty and there is nothing further the description could or should clarify about inputs.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Specific verb ('Return') plus resource ('issues') and source ('Issue tracker API'), which is enough to distinguish it from the singular siblings get_issue/delete_issue. It does not explicitly name those siblings or say how the listing differs from a filtered retrieval, so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no when-to-use context, no prerequisites, and no mention of alternatives such as get_issue for a single issue. The only implicit guidance is that the plural 'issues' suggests bulk retrieval.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

pingA

Check that the Issue Tracker MCP server is running.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.8/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden, but a zero-parameter liveness probe has little behavior to disclose. It does not explicitly state that the call is side-effect-free, requires no auth, or is cheap/low-latency, though a 'ping' by convention implies all of these. Adequate but thin for a no-annotation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence that carries the entire purpose with no filler. Nothing to trim and nothing essential displaced.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return-value semantics need not be spelled out in the description, and the tool has no parameters to document. The description is essentially sufficient for this trivial tool, though it could note that a failed response indicates server unavailability.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies for a parameterless tool.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb (Check) and target (Issue Tracker MCP server is running), and the liveness/health purpose is unmistakably distinct from the issue CRUD siblings (list_issues, get_issue, create_issue, etc.). An agent can tell what this does without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to call this versus alternatives — e.g., as a preflight connectivity check before issue operations, or as a retry after a suspected outage. The description only states the purpose; no usage context or exclusions are implied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_issueC

Update one or more fields of an existing issue.

ParametersJSON Schema

Name	Required	Description	Default
`title`	No
`status`	No
`issue_id`	Yes
`priority`	No
`description`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

C2.7/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden of behavioral disclosure. It does not state that unspecified fields are left unchanged, whether the change is reversible, what permissions are needed, or that issue_id is required and immutable. 'One or more fields' hints at partial update semantics, but that is the only behavioral signal.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler, which is well-structured. It is arguably too terse for five parameters, but there is no wasted language.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with five parameters, zero schema descriptions, and no annotations, this definition leaves too much unspecified. An output schema exists so return values need not be explained, but the partial-update contract and parameter meaning are missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description would need to compensate. It conveys only that some subset of fields may be updated, without naming the updatable fields (title, status, priority, description) or explaining the allowed status/priority enum values or the meaning of null defaults.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb plus resource ('Update ... an existing issue') and clarifies scope with 'one or more fields', which distinguishes it from create_issue and delete_issue by implication. It does not explicitly name those siblings, but the intent is unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no statement of when to use this tool versus siblings, no prerequisite (e.g. the issue must exist), and no guidance on partial vs full updates. The agent must infer usage entirely from the name.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

6 tool updatesv0.1.0Sep 13, 2026
- First observedcreate_issue
- First observeddelete_issue
- First observedget_issue
- First observedlist_issues
- First observedping
- First observedupdate_issue

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.1/5.0

Scored 2026-09-13 20:20 across 6 tools

Disambiguation5/5

Each tool has a clear and distinct purpose: ping for health, and the remaining five tools map cleanly to list/get/create/update/delete operations on issues. There is no overlap or likely misselection between tools.

Naming Consistency5/5

All issue-specific tools follow a consistent verb_noun pattern (list_issues, get_issue, delete_issue, create_issue, update_issue). The only exception is ping, which is a conventional standalone health-check name and does not undermine the pattern.

Tool Count5/5

With 6 tools, the set is well-scoped for a small issue tracker MCP server. Every tool earns its place: five cover the issue lifecycle and one verifies server availability.

Completeness5/5

The tool surface provides full CRUD coverage for issues, including listing, retrieving, creating, updating, and deleting. No core lifecycle operation is missing for the stated purpose.

Maintenance

ActivityMaintained

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

Laraue Boards A
com.laraue
List, view, create, edit, delete, and comment on issues in your Laraue Boards organization.
Developer Tools Product Management Workplace & Productivity
141
mission-controlOAuth
io.github.dinof777
Read and write Mission Control state via MCP — projects, tasks, subtasks, templates, status updates.
Project Management Workplace & Productivity
2
Kaiku A
tech.kaiku.mcp
Kaiku is an issue tracker with a wiki, built so that people and AI agents work in the same place. Its hosted MCP server lets an agent search, read, file and update issues, comment and answer questions, read and write wiki pages, and attach files — with the permissions of the person whose token it uses. Create a token in Settings → Connect over MCP and send it as Authorization: Bearer <token> (or in X-Api-Key); the token says which workspace.
Knowledge & Memory Project Management Workplace & Productivity
761
minddyOAuth
io.github.mangue-dev
Minimal issue tracker: projects, objectives and trackable plans, written by agents over MCP.
Project Management Developer Tools
11

Related MCP Servers

MCP JIRA Server
Project Management App Automation
Warzuponus
A
license
Not graded
quality
D
maintenance
Enables AI applications to manage JIRA issues, workflows, and tasks through a standardized MCP interface, facilitating real-time updates and seamless interaction with JIRA's API.
Updated 6 months ago (2026-04-03 19:50 UTC)
10
MIT
JIRA MCP Server
hackdonalds
A
license
B
quality
D
maintenance
Provides tools for AI assistants to interact with JIRA APIs, enabling them to read, create, update, and manage JIRA issues through standardized MCP tools.
Updated a year ago (2025-07-21 17:54 UTC)
6
4 npm
3
MIT
yandex-tracker-mcp
Project Management Developer Tools
brekhov-ilya
A
license
Not graded
quality
C
maintenance
MCP server for Yandex Tracker API, enabling AI assistants to search, read, create, and edit issues, as well as manage comments, attachments, and links in Yandex Tracker.
Updated 2 months ago (2026-08-03 06:17 UTC)
21 npm
1
MIT
redmine-mcp
Project Management Workplace & Productivity
ytakeuchi0222
F
license
A
quality
D
maintenance
Enables to interact with Redmine issues through the MCP protocol, allowing operations like get, list, create, and update tickets.
Updated 7 months ago (2026-02-19 12:55 UTC)
4
9 npm
-