Skip to main content
Glama
shriramkv

mcp-mock-server

by shriramkv
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

mcp-mock-server

A zero-dependency, configurable mock MCP server for testing MCP clients and harnesses.

When you build an MCP client, an agent, or a testing tool, you need a server to point it at. Spinning up a real one (with real credentials and side effects) just to check that your client speaks the protocol correctly is heavy and flaky. mcp-mock-server is a tiny stand-in: describe your tools and their canned responses in a JSON file, and it serves a correct MCP handshake over stdio.

Part of the AAIF (Agentic AI Innovation Foundation) open-source toolset for the agentic AI ecosystem. It pairs naturally with MCP conformance, audit, and load-testing tools: use the mock as the target while you test the tester.

Highlights

  • Speaks JSON-RPC 2.0 over stdio: initialize, notifications/initialized, ping, tools/list, tools/call.

  • Tools, schemas, and responses are fully driven by a JSON config.

  • Simulates error responses and missing-argument handling for testing sad paths.

  • Simple {argument} templating in responses.

  • Standard library only. No pip dependencies.

Related MCP server: Mock MCP Server

Install

pip install -e .

Requires Python 3.9 or newer.

Quick start

Serve the built-in echo tool:

mcp-mock-server

Print the default config to use as a starting point:

mcp-mock-server --print-default-config > my-tools.json

Serve your own tools:

mcp-mock-server --config examples/weather.json

Config format

{
  "name": "weather-mock",
  "version": "1.0.0",
  "tools": [
    {
      "name": "get_forecast",
      "description": "Return a canned weather forecast for a city.",
      "inputSchema": {
        "type": "object",
        "properties": { "city": { "type": "string" } },
        "required": ["city"]
      },
      "response": { "text": "Forecast for {city}: 30C, clear skies." }
    }
  ]
}

  • inputSchema is standard JSON Schema. Listed required fields are enforced.

  • response.text supports {argument} templating from the call arguments.

  • Set response.isError to true to simulate a tool that fails.

  • If response.text is omitted, the server echoes the arguments back.

Try it by hand

Send a request on stdin (each message is one JSON line):

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
  '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"echo","arguments":{"message":"hello"}}}' \
  | mcp-mock-server

Wiring into an MCP client

Most clients accept a command to launch a server. Point them at:

{
  "mcpServers": {
    "mock": { "command": "mcp-mock-server", "args": ["--config", "my-tools.json"] }
  }
}

Development

pip install -e .
pytest

License

MIT. See LICENSE.

Available Tools

1 tool
echoB

Echo back the provided message.

ParametersJSON Schema
NameRequiredDescriptionDefault
messageYes

TDQS

B3.3/5.0
Behavior2/5

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It simply restates the verb 'echo' without explaining side effects, return format, or confirming that the operation is read-only and side-effect free. The added behavioral context is minimal.

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?

The description is a single sentence with no wasted words. It is appropriately succinct for the simplicity of the tool.

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?

For a trivial tool with one string parameter, the description is largely complete: it states the operation and the input. However, it does not explicitly mention the return value or confirm the absence of side effects, which would enhance completeness.

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?

The input schema defines one required parameter 'message' with no description, and the tool description only refers to 'the provided message' without adding any additional meaning, constraints, or examples. The description fails to compensate for the 0% schema description coverage.

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 uses the specific verb 'Echo back' and clearly identifies the resource as 'the provided message.' It is unambiguous and exactly describes the action, and since there are no sibling tools, no differentiation is needed.

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

Usage Guidelines3/5

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

The intended usage is easily inferred from the name and description, but there is no explicit guidance about when to use this tool versus alternatives or any exclusions. It merely implies usage rather than stating it directly.

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.

  1. 1 tool updatev0.1.0
    • First observedecho
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.2/5.0

Scored across 1 tool

Disambiguation5/5

Only one tool exists, so there is no possibility of confusion between tools. The purpose of echoing a message is unambiguous.

Naming Consistency5/5

The single tool name 'echo' is clear and directly describes its function. With only one tool, naming consistency is trivially satisfied.

Tool Count1/5

The server provides only a single trivial echo tool, which is an extreme mismatch for any meaningful purpose. A server with one trivial tool earns a score of 1.

Completeness1/5

The tool surface is severely incomplete; an echo tool alone provides no meaningful coverage of any domain. There are no additional operations to support a workflow.

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Echo MCP Server

    somacaru
    F
    license
    Not graded
    quality
    D
    maintenance
    A simple demonstration MCP server that provides an echo tool and resource for learning how to build MCP servers. Serves as a starting point and template for creating custom MCP server implementations.
    1
    -

  • Mock MCP Server

    DiscreteTom
    A
    license
    B
    quality
    D
    maintenance
    A mock MCP server for testing MCP client implementations and development workflows. Supports tools, prompts, and resources across multiple transport protocols (stdio, HTTP, SSE).
    1
    MIT

  • mock-mcp

    it370
    F
    license
    Not graded
    quality
    B
    maintenance
    A minimal local HTTP MCP mock server for development and testing, providing predictable tool responses with OAuth token support and zero dependencies.
    -