qiskit-mcp-dev

Qiskit MCP Server Development Guide

Instructions

When helping with MCP server development in this repository:

1. Read existing code first - Check server.py and core modules before adding new functionality
2. Follow established patterns - Match the style of existing tools and tests
3. Include license headers - All new files need the Apache 2.0 header
4. Keep tools async - MCP tools use async def, delegate to core module functions
5. Mock external services - Never call real IBM Quantum APIs in tests
6. Update GitHub CI/CD - New servers require workflow updates (see below)

License Header (Required for all new files)

# This code is part of Qiskit.
#
# (C) Copyright IBM 2025.
#
# This code is licensed under the Apache License, Version 2.0. You may
# obtain a copy of this license in the LICENSE.txt file in the root directory
# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
#
# Any modifications or derivative works of this code must retain this
# copyright notice, and modified files need to carry a notice indicating
# that they have been altered from the originals.

Adding a Tool

Tools go in server.py and delegate to async functions in the core module:

# Example: from qiskit_<name>_mcp_server.<core> import my_function
from qiskit_ibm_runtime_mcp_server.ibm_runtime import my_function

@mcp.tool()
async def my_tool_name(param: str, optional_param: int = 10) -> dict[str, Any]:
    """Clear description of what this tool does.

    Args:
        param: Description of the parameter
        optional_param: Description with default behavior

    Returns:
        Description of the return structure
    """
    return await my_function(param, optional_param)

Key patterns:

• Tool function name ends with _tool suffix
• Docstring describes the tool for AI assistants
• Return type is dict[str, Any]
• Delegate to core module, don't implement logic here

Error Handling Pattern

All tools return consistent response format: