Module 6

MCP Integration

The MCP Connector lets you connect your CRM, database, or internal tools directly to the Messages API, no separate MCP client process required. This module covers the connector, using Resources as a "content catalog," and keeping credentials out of version control.

Answer key Module6_Complete.ipynb
⚠ Heads up: this module is currently broken

The MCP Connector example below does not run end-to-end as written. Read through for the concepts, but expect to adjust the code before it works against a live server. Fix in progress.

1. The MCP Connector

The mcp-client-2025-11-20 beta adds an MCP server as a tool source inline in a /v1/messages request. Claude calls it exactly like any other tool, no orchestration layer needed.

  • Direct: Eliminates the separate MCP client process that standalone MCP servers require.
  • Beta Header: Include mcp-client-2025-11-20 in your request headers.
  • ZDR note: The MCP Connector is not ZDR-eligible because it requires server-side routing.
Free public MCP server for the lab

This module hits Hugging Face's official MCP server at https://huggingface.co/mcp. It's public, anonymous-accessible, and fits the lab's prospecting narrative: Claude can check whether a target prospect publishes models, datasets, or papers on the Hub as a signal of their AI maturity. An HF_TOKEN is optional, it raises rate limits but is not required.

2. Calling the Hugging Face MCP Server

The MCP Connector splits the request into two pieces:

  • mcp_servers, connection details for each remote server (URL, type, auth token). The authorization_token belongs here, not on the tools array.
  • tools with type: "mcp_toolset", references a server by name and enables specific tools through configs. This is your deny-by-default safety boundary, only tools marked {"enabled": true} are exposed to Claude.
Python 
import os

# 1. Define the server connection details separately
# The 'authorization_token' belongs here, not in the tools array
hf_token = os.environ.get("HF_TOKEN")
mcp_servers = [
    {
        "name": "huggingface",
        "type": "url",
        "url": "https://huggingface.co/mcp",
        "authorization_token": hf_token,
    }
]

# 2. Define which tools from that server to enable
# The type MUST be 'mcp_toolset'
tools = [
    {
        "type": "mcp_toolset",
        "mcp_server_name": "huggingface",   # must match the name in mcp_servers
        "configs": {
            "hf_doc_search": {"enabled": True},
            "hf_doc_fetch":  {"enabled": True},
        },
    }
]

response = client.beta.messages.create(
    model="claude-opus-4-7",
    max_tokens=4096,
    mcp_servers=mcp_servers,   # pass the servers array here
    tools=tools,               # pass the toolset array here
    messages=[{
        "role": "user",
        "content": (
            "We're scoping Stripe as an AI consulting prospect. Use the Hugging Face "
            "MCP tools to (1) find any Hugging Face documentation referencing Stripe "
            "or fintech inference patterns, and (2) summarize what Stripe's public AI "
            "footprint suggests about their inference maturity. Cite the docs you used."
        ),
    }],
    betas=["mcp-client-2025-11-20"],
)

3. Resources as a Content Catalog

MCP Resources expose structured data from your server (databases, file trees, API schemas) as a navigable map. Claude reads the resource list to understand what's available before calling tools.

  • Benefit: Reduces expensive exploratory tool calls, Claude can identify the right table or endpoint from the resource catalog without trial-and-error queries.
  • Pattern: Expose your CRM schema and campaign templates as resources so Claude can plan its tool sequence before executing.

4. Securing Credentials

Use environment variable substitution in .mcp.json to keep secrets out of version control. Values written as ${VAR_NAME} are resolved from the runtime environment at startup.

JSON (.mcp.json) 
{
  "mcpServers": {
    "crm": {
      "command": "node",
      "args": ["./mcp-servers/crm-server.js"],
      "env": {
        "CRM_API_KEY": "${CRM_API_KEY}",
        "CRM_BASE_URL": "${CRM_BASE_URL}"
      }
    }
  }
}
Architect Tip for the Exam

Never hardcode API keys in .mcp.json. Use ${VAR_NAME} substitution and add .mcp.json to .gitignore if it contains environment-specific values, or commit a .mcp.json.example template with placeholder variable names.

Lab Exercise: MCP Integration Design

Self-driven lab Module6_Self_Driven_Lab.ipynb

Objective: connect external systems through MCP while keeping secrets and tool descriptions disciplined.

  1. Create a `.mcp.json` configuration that uses environment variable substitution for credentials.
  2. Define at least two MCP Resources that let Claude inspect available CRM or knowledge-base content before calling tools.
  3. Design structured tool errors with retryability and permission signals.
  4. Identify which MCP pieces are not ZDR-eligible and propose a direct-tool alternative.
Expected Deliverable

An MCP integration sketch ready for implementation.