mcp-elicitation-proxy

A transparent MCP proxy that adds elicitation for missing required tool arguments while preserving upstream tool discovery and schemas.

mcp-elicitation-proxy is a standalone Python MCP proxy built on FastMCP. It preserves native upstream tool discovery while adding tool-call middleware for required-field elicitation and sensitive required-field blocking.

The core architectural rule is strict: upstream discovery stays native. The proxy must preserve upstream tools/list output instead of replacing it with a synthetic wrapper such as call_upstream_tool.

Install

Run directly with uvx:

uvx mcp-elicitation-proxy --config config.yaml

For development from a local checkout, use the development setup steps below.

Development Setup

uv sync

Run tests:

uv run pytest -q

Optional lint:

uv run ruff check .

Build artifacts can be produced with uv build. Local outputs under dist/ are not intended to be committed.

Configuration

Example config.yaml with an HTTP upstream:

proxy:
  name: "mcp-elicitation-proxy"

upstream:
  url: "http://localhost:8001/mcp"

elicitation:
  enabled: true
  fallback_on_unsupported: "structured_error"

policies:
  schema_required:
    enabled: true
  sensitive_required:
    enabled: true

tools:
  search_docs:
    required:
      - query
      - project
    elicit:
      message: "Provide the missing search details."
      fields:
        project:
          type: "string"
          description: "Project or scope to search."

Example config.yaml with a command-based upstream:

proxy:
  name: "mcp-elicitation-proxy"

upstream:
  command: "npx"
  args:
    - -y
    - "@modelcontextprotocol/server-everything"

upstream.url and upstream.command are mutually exclusive. Exactly one must be configured. upstream.args defaults to an empty list and is valid only with upstream.command. Command-based upstreams may also provide string environment variables with upstream.env.

Run the proxy:

uv run mcp-elicitation-proxy --config config.yaml

You can also provide the config path via MCP_ELICITATION_PROXY_CONFIG.

MCP Client Configuration

When configuring an MCP client, use mcp-elicitation-proxy as the package and CLI command. The local MCP client server alias can be shorter; the recommended alias is elicitation-proxy.

{
  "mcpServers": {
    "elicitation-proxy": {
      "command": "uvx",
      "args": [
        "mcp-elicitation-proxy",
        "--config",
        "/path/to/config.yaml"
      ]
    }
  }
}

In this example, elicitation-proxy is only the client-local server alias. mcp-elicitation-proxy remains the PyPI package name and CLI command. These names do not need to match. If desired, the proxy's own MCP server name can also be set separately in YAML:

proxy:
  name: "elicitation-proxy"

Discovery Invariants

• Upstream tools remain visible in native tools/list.
• The proxy does not register a generic call_upstream_tool.
• Tool names are not prefixed with values such as upstream_.
• Tool names, descriptions, and input schemas remain the upstream values unless an explicit future discovery feature changes that contract.

The upstream server is delegated to FastMCP native proxying via fastmcp.server.create_proxy(...).

Required Fields And Elicitation

schema_required uses native upstream JSON Schema required fields. Per-tool tools.<tool_name>.required entries are added at runtime for tools/call validation only. Schema-required fields keep their original order, then configured fields are appended without duplicates.

When elicitation.enabled is true, missing non-sensitive required fields may be requested with the client's MCP elicitation capability and merged into the original arguments before forwarding upstream. If elicitation is disabled, unsupported, declined, cancelled, or fails, the proxy returns a structured result instead of calling the upstream tool.

The sensitive_required policy runs before normal required-field elicitation. If a missing required field appears to be a credential or secret, the proxy blocks form-mode elicitation and returns a structured tool_call_blocked result. Complete explicit input is still forwarded.

ambiguous_if and confirm_if settings are parsed for forward-compatible configuration, but advanced ambiguity, confirmation, and LLM-based policies are not implemented in v0.1.0.

Manual Smoke Test With MCP Inspector

A repeatable manual test is available with MCP Inspector and the official @modelcontextprotocol/server-everything reference server.

npx @modelcontextprotocol/inspector -- uv run mcp-elicitation-proxy --config examples/manual-everything.config.yaml

This test verifies command-based upstream startup, native upstream tool discovery, forwarding, elicitation for missing required fields, sensitive-required blocking, and upstream.env propagation.

Expected high-level checks:

• echo is visible as an upstream tool;
• call_upstream_tool is not present;
• tool names are not prefixed with upstream_;
• calling echo with a complete message is forwarded;
• calling echo without message triggers elicitation;
• configured elicitation copy from examples/manual-everything.config.yaml is used;
• marking a missing required field as sensitive blocks elicitation;
• the configured environment variable is visible to the upstream environment tool.

See docs/manual-inspector-test.md for details.

Status

v0.1.0 is the first public-ready baseline. It includes a single-upstream FastMCP proxy, native discovery preservation, required-field elicitation, sensitive required-field blocking, command-based upstream startup, YAML configuration, and automated coverage for the main proxy invariants.