MCP Task Proxy

MCP Task Proxy wraps tools from a remote MCP server with protocol-native background task support. The upstream server does not need to implement MCP tasks.

Container image: ghcr.io/karpikpl/mcp-task-proxy:latest

The proxy:

• mirrors upstream tool names, descriptions, schemas, annotations, and results;
• advertises each tool with execution.taskSupport: "optional";
• runs task-augmented calls in its own background worker;
• exposes tasks/get, tasks/result, tasks/list, and tasks/cancel;
• returns io.modelcontextprotocol/related-task metadata with final results;
• forwards upstream progress notifications into task status updates; and
• continues to support ordinary synchronous tool calls.

Configuration

Variable	Required	Default	Description
UPSTREAM_MCP_URL	Yes	—	Streamable HTTP endpoint of the source MCP server
UPSTREAM_MCP_HEADERS	No	{}	JSON object containing headers sent upstream
UPSTREAM_FORWARD_HEADERS	No	Authorization	Comma-separated incoming headers to forward upstream
HOST	No	0.0.0.0	Proxy listen address
PORT	No	8080	Proxy listen port
FASTMCP_DOCKET_URL	No	memory://	Task backend; use Redis for persistence and scaling

The default in-memory task backend is suitable for local development and a single server process. Use a shared Redis or Valkey endpoint for production:

export FASTMCP_DOCKET_URL=redis://redis:6379/0

Run locally

export UPSTREAM_MCP_URL=https://example.com/mcp
uv sync
uv run mcp-task-proxy

The proxy MCP endpoint is http://localhost:8080/mcp; health is available at http://localhost:8080/health.

Docker

docker build -t mcp-task-proxy .
docker run --rm -p 8080:8080 \
  -e UPSTREAM_MCP_URL=https://example.com/mcp \
  mcp-task-proxy

To pass upstream headers:

docker run --rm -p 8080:8080 \
  -e UPSTREAM_MCP_URL=https://example.com/mcp \
  -e 'UPSTREAM_MCP_HEADERS={"Authorization":"Bearer token"}' \
  mcp-task-proxy

Client behavior

Task-aware clients can request background execution:

import asyncio

from fastmcp import Client


async def main() -> None:
    async with Client("http://localhost:8080/mcp") as client:
        task = await client.call_tool(
            "slow_upstream_tool",
            {"value": "example"},
            task=True,
        )
        print(task.task_id)
        print(await task.result())


asyncio.run(main())

Clients that do not augment the call with task metadata receive the upstream result synchronously.

The proxy forwards the incoming Authorization header during authenticated tool discovery, synchronous calls, and background task execution. Forwarding is restricted to UPSTREAM_FORWARD_HEADERS; request headers override matching static values in UPSTREAM_MCP_HEADERS. The proxy relays credentials but does not validate them itself.

For OAuth-capable upstream servers, the proxy exposes RFC 9728 metadata at /.well-known/oauth-protected-resource and /.well-known/oauth-protected-resource/mcp. It retrieves the path-aware metadata document from the upstream server, preserves its authorization servers and scopes, and rewrites resource to the proxy's public /mcp URL. For Databricks Genie One, this preserves the required genie and offline_access scopes and the workspace /oidc authorization server.

Upstream tools are discovered and cached on the first authenticated client request. Restart the proxy after the upstream adds, removes, or changes tools.

Limitations

• The proxy can report real progress only when the upstream sends MCP progress notifications. Otherwise task status remains working until completion.
• Cancellation stops the proxy task cooperatively but cannot guarantee that the upstream operation stops.
• In-memory tasks are lost when the proxy restarts and cannot be shared across replicas.