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

async def fetch_url(url: str) -> str:
    async with httpx.AsyncClient(headers={"Person-Agent": USER_AGENT}) as consumer:
        attempt:
            response = await consumer.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 forth.
            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 primary act: the precise software operate that Claude will name.

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

1. Examine if that library is supported
2. Construct a site-specific search question (e.g., website: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 thing into a pleasant, readable string that Claude can perceive and return

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

@mcp.software()  
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 software. Supported libraries: {', '.be part of(docs_urls.keys())}")
    
    question = f"website:{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 = outcome["link"]
        title = outcome.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 thing 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 all the time 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 most important methods to check your MCP server:

Growth Mode (Beneficial for Constructing & Testing)

The best approach to take a look at your server throughout improvement 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 instances
• Set or override surroundings variables briefly

Use this mode whereas constructing and debugging. You’ll be capable of see precisely what Claude would see and shortly repair any points earlier than integrating with the complete 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) routinely
• Allow it to run each time you launch Claude Desktop
• Make it accessible by 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 difficulty 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 should you put in it regionally 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 the event you’re not utilizing VS Code, change 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/most important.py"
  ]
}

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

• To search 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 software, and anytime you open the Developer Instruments (🔨), it’ll present up. You may chat with Claude and ask issues like:

“Are you able to verify the newest MCP docs for learn how to construct a customized server?”

And Claude will name your server, search the docs, pull the content material, and use it in its response — stay. You may 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 software that extends an LLM’s capabilities in a modular, safe, and highly effective means.

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

• How MCP works below the hood
• The right way to construct and expose instruments Claude can use
• The right way to wire up real-time net search and content material extraction
• The right 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 a complete 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 software 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