How I Finally Understood MCP — and Got It Working in Real Life

async def fetch_url(url: str) -> str:
    async with httpx.AsyncClient(headers={"Consumer-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 important content material and take away navigation, sidebars, and many others.
            main_content = soup.discover("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 primary act: the precise instrument operate that Claude will name.

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

1. Verify 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 the whole lot 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.instrument()  
async def get_docs(question: str, library: str) -> str:
    """
    Search the most recent 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:
        increase ValueError(f"Library {library} not supported by this instrument. 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 the whole lot off. It tells the MCP server to start out listening for enter from Claude utilizing customary enter/output (which is how Claude Desktop talks to exterior instruments). This line at all times lives on the backside of your script.

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

Step 5: Check 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 important methods to check your MCP server:

Improvement Mode (Beneficial for Constructing & Testing)

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

mcp dev important.py

This command launches the MCP Inspector, which opens up an area internet interface in your browser. It’s like a management panel to 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 atmosphere variables quickly

Use this mode whereas constructing and debugging. You’ll be capable of see precisely what Claude would see and rapidly 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 important.py

This command will:

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

However maintain on — there’s one small catch…

⚠️ Present Difficulty: uv Command Is Hardcoded

Proper now, there’s an open situation 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 obtainable in your PATH — which isn’t at all times the case, particularly if you happen to 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

💡 In case you’re not utilizing VS Code, substitute code along 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/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 substitute "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/important.py"
  ]
}

4. Save the file and restart Claude Desktop.

✅ That’s It!

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

“Are you able to examine the most recent 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 possibly can view a fast demo 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 instrument that extends an LLM’s capabilities in a modular, safe, and highly effective approach.

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

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

You didn’t simply study 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 instrument 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