Skip to content

Reading a resource template makes an extra worker-thread round trip to return a value it already has #3889

Open

Description

@patrick-immometrica

Description

What happens

ResourceTemplate.create_resource (src/mcp/server/mcpserver/resources/templates.py) runs the template function, then wraps the result as FunctionResource(fn=lambda: result). FunctionResource.read() sees a sync callable and calls anyio.to_thread.run_sync(self.fn). So every template read crosses into a worker thread just to return a constant:

  • sync template function: 2 hops per read (the function itself, then the lambda)
  • async template function: 1 hop per read, where it needs none

Expected

1 hop for a sync template function (to run it), 0 for an async one.

Repro

import anyio
import anyio.to_thread

from mcp import Client
from mcp.server.mcpserver import MCPServer

hops = 0
_run_sync = anyio.to_thread.run_sync


async def counting_run_sync(func, *args, **kwargs):
    global hops
    hops += 1
    return await _run_sync(func, *args, **kwargs)


anyio.to_thread.run_sync = counting_run_sync

mcp = MCPServer("demo")


@mcp.resource("users://{user_id}")
def user(user_id: str) -> str:
    return f"user {user_id}"


@mcp.resource("orders://{order_id}")
async def order(order_id: str) -> str:
    return f"order {order_id}"


async def main() -> None:
    global hops
    async with Client(mcp) as client:
        for uri in ("users://1", "orders://1"):
            hops = 0
            await client.read_resource(uri)
            print(f"{uri}: {hops} worker-thread hop(s)")


anyio.run(main)

Output on main (77001c9):

users://1: 2 worker-thread hop(s)
orders://1: 1 worker-thread hop(s)

Cost

Interleaved before/after runs of 1000–2000 template reads, median wall time. The gain depends on the transport, so here are all of them:

  • in-process Client(server): -33% (sync template), -35% (async template)
  • legacy JSON-RPC streams, 100 reads in flight: -25% (sync template), -13% (async template)
  • legacy JSON-RPC streams, sequential: -5% to -22% across runs
  • streamable HTTP, SSE responses, sequential: -9% to -14%
  • streamable HTTP, JSON responses: about -20% sequential (borderline), about 0% with 100 in flight

The machine was loaded (load average around 10), so the numbers are noisy. Over HTTP the hop is a small part of each request.

Possible fix

Wrap the result in async def value(): return result and pass fn=value. The content returned is the same. The one visible difference: for template-built resources, FunctionResource.fn becomes a coroutine function instead of a plain callable. I couldn't find anything in the repo that calls .fn() directly. I have a branch with this and a test, and I'm happy to open a PR if it's wanted.

Python 3.12.16, macOS 27.2 (Apple M5), mcp at 77001c9, anyio 4.14.2, pydantic 2.12.5.

References

Disclosure: an AI assistant helped me find and benchmark this. I checked the repro output myself.

Activity

  1. added
    enhancementRequest for a new feature that's not currently supported
    on Nov 21, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementRequest for a new feature that's not currently supported

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions