Skip to main content

MCP Ingestion

MCP ingestion maps model-context-protocol tool definitions into the same ToolSchema surface used by OpenAPI and Python tools.

Role In The Catalog​

MCP tools usually arrive with better runtime descriptions than raw enterprise OpenAPI specs, but they still benefit from graph retrieval:

  • consistent annotations
  • category and relation analysis
  • candidate filtering
  • compact tool lists for the LLM
  • shared validation gates

Ingest A Tool List​

Use ingest_mcp_tools() when the adapter already has an MCP tools/list response.

from graph_tool_call.ingest.mcp import ingest_mcp_tools

schemas = ingest_mcp_tools(
    [
        {
            "name": "read_file",
            "description": "Read a file",
            "inputSchema": {
                "type": "object",
                "properties": {
                    "path": {"type": "string", "description": "File path"}
                },
                "required": ["path"],
            },
            "annotations": {"readOnlyHint": True},
        }
    ],
    server_name="filesystem",
)

The parser preserves MCP annotations such as readOnlyHint, destructiveHint, and enum values on parameters.

Ingest Into A Graph​

from graph_tool_call import ToolGraph

graph = ToolGraph()
graph.ingest_mcp_tools(mcp_tools, server_name="filesystem")

for tool in graph.retrieve("read a configuration file", top_k=3):
    print(tool.name)

ToolGraph.ingest_mcp_tools() registers the schemas and can run dependency detection using the same graph relation logic as other tool sources.

Fetch From An MCP Endpoint​

For HTTP JSON-RPC MCP endpoints that support tools/list:

from graph_tool_call import ToolGraph

graph = ToolGraph()
graph.ingest_mcp_server(
    "https://mcp.example.com/mcp",
    timeout=30,
    max_response_bytes=5_000_000,
)

Private hosts are blocked by default. Enable them only from trusted infrastructure:

graph.ingest_mcp_server(
    "http://127.0.0.1:3000/mcp",
    allow_private_hosts=True,
)

Normalized Metadata​

FieldPurpose
metadata.sourceset to mcp
metadata.mcp_serverserver name from argument, serverInfo, or hostname
tagsincludes the server name when available
annotationsMCP safety and behavior hints
parametersnormalized input schema properties

Adapter Boundary​

The graph engine should not own MCP server credentials or runtime transport state. Keep connection details in the MCP proxy, then pass normalized schemas to the graph.

Failure Modes​

SymptomLikely CauseFix
invalid JSONserver did not return a JSON-RPC responseverify endpoint and transport
no tools detectedresponse lacks result.tools or toolsinspect the MCP server tools/list output
private host blockedendpoint is local/internalopt in from trusted infrastructure only
destructive tool ranked too highannotations or query intent are weakpreserve destructiveHint and add validation cases

Validation​

poetry run pytest tests/test_ingest_mcp.py tests/test_mcp_annotations.py -q