MCP Server Support

What is MCP?

Model Context Protocol (MCP) is an open standard that lets LLMs interact with external tools and data through a structured interface. An MCP server exposes tools: named, schema-validated operations (e.g. “search the model database”, “validate a NeuroML file”, “run code”). A tool call is what happens when the model decides to use one of those tools: the client asks the server to list its tools (tools/list), the model picks the right one and supplies arguments, the client invokes it (tools/call), and the tool result is returned to the model as context for the next step.

How Klea uses MCP

Klea acts as the MCP client: it uses MCP servers to give its LLMs access to external tools (validation, file handling, model lookup, code execution, etc.). A domain in a RAG or agent config can declare one or more MCP servers; the tools they expose are fetched at startup and made available to the graph’s tool picker, which decides which tools to call for a given query.

Configuring MCP servers

Each domain lists the MCP servers it can use under mcp_servers. Each entry maps a server name to the URL of a streamable HTTP MCP endpoint:

{
    "domains": {
        "NeuroML": {
            "mcp_servers": {
                "NeuroML": {
                    "url": "http://127.0.0.1:8542/mcp"
                }
            }
        }
    }
}

See Create and use a RAG system for a full example and the Deploying Klea RAG on HuggingFace Spaces cookbook for a deployed setup. The NeuroML package ships with nml-mcp, an MCP server exposing tools for NeuroML model generation, validation, and lookup.

How Klea uses the tools

At startup, the graph connects to each configured MCP server, lists its tools, and stores per-domain metadata. The tool picker node then selects the tools relevant to the current query, and the selected tools are called during graph execution. When several MCP servers are configured, fastmcp prefixes tool names with the server name (e.g. NeuroML_list_files_tool) so tools from different servers stay distinct; Klea keeps these prefixed names unchanged.

Writing tools for Klea

Klea expects MCP tool functions to follow a docstring-first convention, so that the LLM-facing description stays concise and parameter details are available in the tool schema:

  1. Tool description – the opening text block of the function docstring (what the tool does, when to use / not use it, and one short example). Keep this block focused; it is what the tool picker shows the LLM.

  2. Parameters – describe each parameter in a Google-style Args: section. fastmcp parses these into the tool’s input schema, and Klea renders them as compact one-line parameter entries (name, type, required flag, description).

  3. Do not set the tool description to the raw full docstring. Klea shows the opening text block as the description and the Args:-derived schema as the parameter list, so duplicating the Args:/Returns: prose in the description wastes prompt tokens.

Example:

@tool_meta(ToolInfo(title="Find models on NeuroML-db"))
async def get_models_from_neuromldb_tool(
    search_query: str, num: int = 3, download: bool = False
) -> dict:
    """Search and optionally download cell and ion channel models from
    NeuroML-DB.

    Use this tool when you need example cell or ion channel models, or
    want to download models for local use.

    Use when:
    - Finding example cell and ion channel models.
    - Downloading models for use in your project.

    Do not use for:
    - Creating or editing NeuroML models (use the model template tool
      instead).
    - Running simulations (use the simulation tools instead).

    Example: get_models_from_neuromldb(search_query="cerebellum", download=True)

    Args:
        search_query: search term for querying NeuroML-DB.
        num: number of search results to get (clamped to 1-20).
        download: set to true to also download the models.

    Returns:
        Dictionary of model information with metadata and model content.
    """
    ...

Tool functions must end with _tool for automatic registration (see neuroml_mcp.utils.register_tools), and carry @tool_meta(ToolInfo( title=..., tags=...)) metadata. Validation constraints (e.g. Field(min_length=1)) may be added to parameter annotations and are preserved in the schema.

Tool description length and style

The tool description is what the model uses to decide which tool to call, so it is worth writing carefully. A good rule of thumb is that a description should read like a short, structured “how to use this tool” note: roughly 100-250 tokens per tool. This keeps the whole tool list small enough to scale while still giving smaller models the guidance they need to pick the right tool. Sources consulted:

  • Anthropic – “Define tools” (https://docs.claude.com/en/docs/agents-and-tools/tool-use/define-tools) calls the description “by far the most important factor in tool performance” and recommends at least 3-4 sentences covering what the tool does, when it should (and should not) be used, what each parameter means, and any important caveats or limitations. Descriptions are input tokens, so they count against the context window on every request.

  • OpenAI – “Function calling” (https://platform.openai.com/docs/guides/function-calling) recommends clearly describing the purpose of each function and parameter and including examples and edge cases, and suggests shortening descriptions when under token pressure and keeping fewer than ~20 tools available at once.

  • MCP specification – “Tools” (https://modelcontextprotocol.io/specification/2025-06-18/server/tools) defines description as a “human-readable description of functionality” and gives no length guidance, so the length is up to the server author.

  • opencode (an open-source agentic coding tool, https://github.com/sst/opencode) keeps its core tool descriptions terse (~50-125 tokens) but ships richer, structured descriptions for its CLI tools (~100-600 tokens) that open with a one-sentence summary and use “Use when” / “Do NOT use” bullet sections and examples. Its guidance: “Keep the tool description concise; the full schema documentation remains in the signature.”

Klea’s docstring-first convention (above) is a middle ground that keeps descriptions small enough to scale:

  • One-sentence summary on the first line.

  • A short “Use this tool to …” sentence.

  • “Use when:” and “Do not use for:” bullet sections with cross-tool pointers, so smaller models can pick the right tool.

  • One concrete “Example:” line.

  • Parameter descriptions in a Google-style Args: section (parsed into the schema by fastmcp) rather than in the description.

  • No long procedural prose (template structure, next steps, error handling, performance notes): that adds tokens without helping tool selection.

Reusable template

Copy this template when implementing a new tool; fill in the placeholders and keep the whole block to roughly 100-250 tokens:

"""<One-sentence summary of what the tool does>.

Use this tool to <primary purpose>.

Use when:
- <case where this tool is the right choice>
- <another concrete case>

Do not use for:
- <case better handled elsewhere> (use the <role> tool instead)

Example: <tool_name>(<param>=<value>)

Args:
    <param>: <what the parameter means and how it affects behaviour>.
    <param2>: <description>. Defaults to <default> if not specified.

Returns:
    <brief description of the data returned>.
"""

Use generic role references (“use the file reading tool”) rather than exact tool names in the “Do not use for” pointers, because fastmcp prefixes tool names with the server name (NeuroML_list_files_tool) and those prefixes vary between deployments.