mcp-elicitation-proxy

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

mcp-elicitation-proxyis 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 upstreamtools/listoutput instead of replacing it with a synthetic wrapper such ascall_upstream_tool.

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

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

Build artifacts can be produced withuv build. Local outputs underdist/are not intended to be committed.

Exampleconfig.yamlwith 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."

Exampleconfig.yamlwith a command-based upstream:

proxy: name: "mcp-elicitation-proxy" upstream: command: "npx" args: - -y - "@modelcontextprotocol/server-everything"

upstream.urlandupstream.commandare mutually exclusive. Exactly one must be configured.upstream.argsdefaults to an empty list and is valid only withupstream.command. Command-based upstreams may also provide string environment variables withupstream.env.

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

You can also provide the config path viaMCP_ELICITATION_PROXY_CONFIG.

When configuring an MCP client, usemcp-elicitation-proxyas the package and CLI command. The local MCP client server alias can be shorter; the recommended alias iselicitation-proxy.

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

In this example,elicitation-proxyis only the client-local server alias.mcp-elicitation-proxyremains 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"

- Upstream tools remain visible in nativetools/list.
- The proxy does not register a genericcall_upstream_tool.
- Tool names are not prefixed with values such asupstream_.
- 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 viafastmcp.server.create_proxy(...).

schema_requireduses native upstream JSON Schemarequiredfields. Per-tooltools.<tool_name>.requiredentries are added at runtime fortools/callvalidation only. Schema-required fields keep their original order, then configured fields are appended without duplicates.

Whenelicitation.enabledistrue, 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.

Thesensitive_requiredpolicy 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 structuredtool_call_blockedresult. Complete explicit input is still forwarded.

ambiguous_ifandconfirm_ifsettings are parsed for forward-compatible configuration, but advanced ambiguity, confirmation, and LLM-based policies are not implemented inv0.1.0.

A repeatable manual test is available with MCP Inspector and the official@modelcontextprotocol/server-everythingreference 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, andupstream.envpropagation.

- echois visible as an upstream tool;
- call_upstream_toolis not present;
- tool names are not prefixed withupstream_;
- callingechowith a completemessageis forwarded;
- callingechowithoutmessagetriggers elicitation;
- configured elicitation copy fromexamples/manual-everything.config.yamlis used;
- marking a missing required field as sensitive blocks elicitation;
- the configured environment variable is visible to the upstream environment tool.

Seedocs/manual-inspector-test.mdfor details.

MCP bridge that lets Claude Code delegate heavy tasks to the Antigravity CLI (agy) — purpose-built tools, model routing with fallback, session continuity, and output truncation to save Claude's context and tokens.