How I Lastly Understood MCP — and Bought It Working in Actual Life

async def fetch_url(url: str) -> str:
    async with httpx.AsyncClient(headers={"Person-Agent": USER_AGENT}) as shopper:
        strive:
            response = await shopper.get(url, timeout=30.0)
            response.raise_for_status()
            soup = BeautifulSoup(response.textual content, "html.parser")
            
            # Attempt to extract most important content material and take away navigation, sidebars, and so on.
            main_content = soup.discover("most important") or soup.discover("article") or soup.discover("div", class_="content material")
            
            if main_content:
                textual content = main_content.get_text(separator="n", strip=True)
            else:
                textual content = soup.get_text(separator="n", strip=True)
                
            # Restrict content material size if it is too giant
            if len(textual content) > 8000:
                textual content = textual content[:8000] + "... [content truncated]"
                
            return textual content
        besides httpx.TimeoutException:
            return "Timeout error when fetching the URL"
        besides httpx.HTTPStatusError as e:
            return f"HTTP error occurred: {e}"

Now comes the principle act: the precise device perform that Claude will name.

The get_docs perform is the place every little thing comes collectively. Claude will go it a question and the identify of a library (like "llama-index"), and this perform will:

1. Test if that library is supported
2. Construct a site-specific search question (e.g., web site:docs.llamaindex.ai "vector retailer")
3. Use search_web() to get the highest outcomes
4. Use fetch_url() to go to and extract the content material
5. Format every little thing into a pleasant, readable string that Claude can perceive and return

We additionally embody titles, URLs, and a few visible separators between every consequence, so Claude can reference or cite them if wanted.

@mcp.device()  
async def get_docs(question: str, library: str) -> str:
    """
    Search the newest docs for a given question and library.
    Helps langchain, openai, mcp and llama-index.

    Args:
        question: The question to seek for (e.g. "Chroma DB")
        library: The library to go looking in (e.g. "langchain")

    Returns:
        Textual content from the docs
    """
    if library not in docs_urls:
        elevate ValueError(f"Library {library} not supported by this device. Supported libraries: {', '.be part of(docs_urls.keys())}")
    
    question = f"web site:{docs_urls[library]} {question}"
    outcomes = await search_web(question)
    
    if not outcomes or len(outcomes.get("natural", [])) == 0:
        return "No outcomes discovered"
    
    combined_text = ""
    for i, end in enumerate(outcomes["organic"]):
        url = consequence["link"]
        title = consequence.get("title", "No title")
        
        # Add separator between outcomes
        if i > 0:
            combined_text += "nn" + "="*50 + "nn"
            
        combined_text += f"Supply: {title}nURL: {url}nn"
        page_content = await fetch_url(url)
        combined_text += page_content
    
    return combined_text

Lastly, this line kicks every little thing off. It tells the MCP server to begin listening for enter from Claude utilizing customary enter/output (which is how Claude Desktop talks to exterior instruments). This line all the time lives on the backside of your script.

if __name__ == "__main__":
    mcp.run(transport="stdio")

Step 5: Take a look at and Run Your Server

Alright, your server is coded and able to go — now let’s run it and see it in motion. There are two most important methods to check your MCP server:

Improvement Mode (Advisable for Constructing & Testing)

The best option to take a look at your server throughout growth is to make use of:

mcp dev most important.py

This command launches the MCP Inspector, which opens up a neighborhood net interface in your browser. It’s like a management panel on your server.

Right here’s what you are able to do with it:

• Interactively take a look at your instruments (like get_docs)
• View detailed logs and error messages in actual time
• Monitor efficiency and response occasions
• Set or override surroundings variables briefly

Use this mode whereas constructing and debugging. You’ll have the ability to see precisely what Claude would see and shortly repair any points earlier than integrating with the total Claude Desktop app.

Claude Desktop Integration (For Common Use)

As soon as your server works and also you’re pleased with it, you possibly can set up it into Claude Desktop:

mcp set up most important.py

This command will:

• Add your server into Claude’s configuration file (the JSON file we fiddled with earlier) mechanically
• Allow it to run each time you launch Claude Desktop
• Make it accessible via the Developer Instruments (🔨 hammer icon)

However maintain on — there’s one small catch…

⚠️ Present Concern: uv Command Is Hardcoded

Proper now, there’s an open problem within the mcp library: when it writes your server into Claude’s config file, it hardcodes the command as simply "uv". That works solely if uv is globally accessible in your PATH — which isn’t all the time the case, particularly for those who put in it domestically with pipx or a customized technique.

So we have to repair it manually. Right here’s how:

Manually Replace Claude’s Config File

1. Open your Claude config file:

On MacOS:

code ~/Library/Utility Help/Claude/claude_desktop_config.json

On Home windows:

code $env:AppDataClaudeclaude_desktop_config.json

💡 Should you’re not utilizing VS Code, change code together with your textual content editor of alternative (like open, nano, or subl).

2. Discover the part that appears like this:

"docs": {
  "command": "uv",
  "args": [
    "run",
    "--with",
    "mcp[cli]",
    "mcp",
    "run",
    "/PATH/TO/mcp-server/most important.py"
  ]
}

3. Replace the "command" worth to absolutely the path of uv in your system.

• To seek out it, run this in your terminal:

which uv

• It’ll return one thing like:

/Customers/your_username/.native/bin/uv

• Now change "uv" within the config with that full path:

"docs": {
  "command": "/Customers/your_username/.native/bin/uv",
  "args": [
    "run",
    "--with",
    "mcp[cli]",
    "mcp",
    "run",
    "PATH/TO/mcp-server/most important.py"
  ]
}

4. Save the file and restart Claude Desktop.

✅ That’s It!

Now Claude Desktop will acknowledge your customized docs device, and anytime you open the Developer Instruments (🔨), it’ll present up. You may chat with Claude and ask issues like:

“Are you able to examine the newest MCP docs for how one can construct a customized server?”

And Claude will name your server, search the docs, pull the content material, and use it in its response — dwell. You may view a fast demo right here.

🎉 Congrats, You’ve Mastered MCP!

You probably did it. You’ve gone from zero to constructing, testing, and integrating your very personal Claude-compatible MCP server — and that’s no small feat.

Take a second. Stretch. Sip some espresso. Pat your self on the again. You didn’t simply write some Python — you constructed an actual, production-grade device that extends an LLM’s capabilities in a modular, safe, and highly effective means.

Severely, most devs don’t get this far. You now perceive:

• How MCP works beneath the hood
• The way to construct and expose instruments Claude can use
• The way to wire up real-time net search and content material extraction
• The way to debug, take a look at, and combine the entire thing with Claude Desktop

You didn’t simply be taught it — you shipped it.

Wish to go even deeper? There’s an entire world of agentic workflows, customized instruments, and collaborative LLMs ready to be constructed. However for now?

Take the win. You earned it. 🏆

Now go ask Claude one thing enjoyable and let your new device flex.

References

[1] Anthropic, Mannequin Context Protocol: Introduction (2024), modelcontextprotocol.io
[2] LangChain, MCP From Scratch (2024), Notion
[3] A. Alejandro, MCP Server Instance (2024), GitHub Repository
[4] O. Santos, Integrating Agentic RAG with MCP Servers: Technical Implementation Information (2024), Medium