Example - Connecting to MCP server hosted via "npx" & implement it for Claude Python API

[ArsenicBismuth]

Hi, I got stuck on this quite a bit so I wanted to share my solution. I'm trying to connect Brave Web Search to my custom AI assistant (using Anthropic's Python API). Turns out I got various issues supplying "npx" directly to the command list.

What you should do is using shutil.which() like below:

# Create server parameters for stdio connection
server_params = StdioServerParameters(
    command=shutil.which("npx"),    # Because it can't check PATH
    args=["-y", "@modelcontextprotocol/server-brave-search"],
    env=os.environ.copy()           # Provide all default env variable so that node can work properly
)
server_params.env["BRAVE_API_KEY"] = <YOUR_BRAVE_API_KEY> # Then add the API key

Also note that you can't pass env with dict containing the API key directly, because npx command requires some other env variables. So, while None would work to call the npx command, you can't pass your API key in here.

If the maintainer doesn't mind, I can make a PR to add this example to the README.

---

UPDATE: You can check the detailed information in the comments.

To sum it up, after you initialized the parameters for the server:

1. initialize the connection

# During initialization
async with stdio_client(server_params) as (read, write):
    async with ClientSession(read, write) as session:
        # Initialize the connection with MCP server
        await session.initialize()

        tools_list = await session.list_tools()
        tool = tools_list.tools

2. Connect the tools to your Claude:

response_msg = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=1000,
    temperature=0,
    system=system_prompt,
    messages=message,
    tools=tools
)

3. Then, add some check if the AI tries to invoke a tool_use, then call the tool with its input

if (response_msg.stop_reason == "tool_use"):
    tool_use = response_msg.content[-1]
    tool_name = tool_use.name
    tool_input = tool_use.input


    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            await session.call_tool(tool_name, tool_input)

Do note, to call a tool, the connection MUST be maintained. Which is why I need the session context before calling the tool.

[ArsenicBismuth]

Tho, right now I have 0 clue on how to make my Claude (in Python) connect or use tools in my MCP. Any pointers would be appreciated.

Most of the documentation talks about the servers, and not much about the client.

UPDATE: I show my full implementation in the comment below.

[ArsenicBismuth]

Here's relevant documentation in the Claude Python API on tool calling: https://modelcontextprotocol.io/docs/concepts/tools

I try to provide my Claude with the tools obtained from the MCP session:

# During initialization
async with stdio_client(server_params) as (read, write):
    async with ClientSession(read, write) as session:
        # Initialize the connection with MCP server
        await session.initialize()

        tools_list = await session.list_tools()
        tool = tools_list.tools

Here, you will get tool data like below. This is similar to what the Claude Python API expecting in the link I shared above. But format is a bit different (it uses inputSchema, while Claude Python API expects input_schema).

[Tool(name='brave_web_search', description='Performs a web search... ', inputSchema={'type': 'object', 'properties': {'query': {'type': 'string', 'description': 'Search query (max 400 chars, 50 words)'}, 'count': {'type': 'number', 'description': 'Number of results (1-20, default 10)', 'default': 10}, 'offset': {'type': 'number', 'description': 'Pagination offset (max 9, default 0)', 'default': 0}}, 'required': ['query']}), Tool(name='brave_local_search', description="Searches for local businesses...", inputSchema={'type': 'object', 'properties': {'query': {'type': 'string', 'description': "Local search query (e.g. 'pizza near Central Park')"}, 'count': {'type': 'number', 'description': 'Number of results (1-20, default 5)', 'default': 5}}, 'required': ['query']})]

And then I supply the tools like so. And it seems my Claude is indeed using the tools when necessary. Just need to do the handling (apparently it's not automatic?).

response = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=1000,
    temperature=0,
    system=system_prompt,
    messages=message,
    tools=tools
)

[ArsenicBismuth]

You will get results like this:

[TextBlock(text="Oh! I'm reading about this super cool article about Boston Dynamics' latest robot! Let 
me search for the newest updates about them!", type='text'), ToolUseBlock(id='toolu_01QR7aWtcADXdRt7zLCjFSkK', input={'query': 'Boston Dynamics latest robot development news'}, name='brave_web_search', type='tool_use')]

Handle the tool call request using call_tool(), and then handle the output like outlined in the documentation:

[dsp-ant]

@ArsenicBismuth MCP is mostly concerned with obtaining the definition for the tools. Please refer to the Anthropic Python SDK for how to implement tool use. When you hand a tool to the Anthropic API, it might return a ToolUseBlock. The client (your custom application) should handle this, find the appropriate MCP tool and then use call_tool to ask the server to call the tool and return the result. this then needs to get passed to Anthropic SDK (in the way it expects this). I hope this makes sense.

sequenceDiagram
    box gray Custom app
        participant SDK as Anthropic SDK
        participant Client as MCP Client
    end
    participant Server as MCP Server

    SDK->>Client: ToolUseBlock
    Client->>Server: call_tool()
    Server-->>Client: Tool result
    Client->>SDK: Tool result

Loading

I think we should certainly improve the docs to include clients integration. If you don't mind opening an issue in the docs repository?

[ArsenicBismuth]

@dsp-ant Oh yeah your instruction is clear, I originally opened this discussion to get some pointers, but as you can see I managed to solve everything on my own. Thanks!

If you don't mind opening an issue in the docs repository?

Sure I will do that.

[mii9000]

@ArsenicBismuth is your code for the above open? it would be helpful to use it as a reference

[jspahrsummers]

Are you on Windows by chance? There's a known issue with npx and MCP servers there: modelcontextprotocol/servers#40.

Regardless, will close this out as resolved. Thanks for documenting your solution!

[ArsenicBismuth]

I mean, I open this as a discussion and not an "issue" because it isn't one. Meanwhile I did open an issue I found in here: modelcontextprotocol/python-sdk#74

But it's unrelated to any of the point maintained in the issue you linked. Because I don't use the Claude Desktop App.

[kzmszk]

As for npx path problem, my workaround is like bellow:
Just setting path variable in env explicitly.
You don't need shutil or something special in client code side.

{
      "github": {
        "command": "npx",
        "args": [
          "-y",
          "@modelcontextprotocol/server-github"
        ],
        "env": {
          "GITHUB_PERSONAL_ACCESS_TOKEN": "my-token",
          "PATH": "/opt/homebrew/bin:/usr/bin:/bin"
        }
  }