MCP Integration

This guide explains how to integrate the Nevermined Payments Python SDK with MCP (Model Context Protocol) servers.

Overview

MCP (Model Context Protocol) enables AI applications to interact with external tools, resources, and prompts. The Nevermined SDK provides built-in MCP integration to:

Protect tools, resources, and prompts with paywalls
Handle OAuth 2.1 authentication
Manage credit consumption per operation

MCP Integration API

Access the MCP integration through payments.mcp:

from payments_py import Payments, PaymentOptions

payments = Payments.get_instance(
    PaymentOptions(nvm_api_key="nvm:your-key", environment="sandbox")
)

# MCP integration is available as:
mcp = payments.mcp

Simplified API (Recommended)

The simplified API handles server setup automatically:

Register a Tool

async def hello_handler(args, context=None):
    """Handle the hello tool request."""
    name = args.get("name", "World")
    return {
        "content": [{"type": "text", "text": f"Hello, {name}!"}]
    }

# Register the tool
payments.mcp.register_tool(
    name="hello_world",
    config={
        "description": "Says hello to someone",
        "inputSchema": {
            "type": "object",
            "properties": {
                "name": {"type": "string", "description": "Name to greet"}
            }
        }
    },
    handler=hello_handler,
    options={"credits": 1}  # Cost: 1 credit per call
)

Register a Resource

async def config_handler(uri, variables, context=None):
    """Handle the configuration resource request."""
    return {
        "contents": [{
            "uri": str(uri),
            "mimeType": "application/json",
            "text": '{"version": "1.0.0", "feature_flags": {"beta": true}}'
        }]
    }

payments.mcp.register_resource(
    uri="data://config",
    config={
        "name": "Configuration",
        "description": "Application configuration",
        "mimeType": "application/json"
    },
    handler=config_handler,
    options={"credits": 2}  # Cost: 2 credits per access
)

Register a Prompt

async def greeting_handler(args, context=None):
    """Handle the greeting prompt request."""
    style = args.get("style", "formal")
    return {
        "messages": [{
            "role": "user",
            "content": {
                "type": "text",
                "text": f"Please greet me in a {style} way."
            }
        }]
    }

payments.mcp.register_prompt(
    name="greeting",
    config={
        "name": "Greeting",
        "description": "Generates a greeting"
    },
    handler=greeting_handler,
    options={"credits": 1}
)

Start the Server

import asyncio

async def main():
    # Register handlers first
    payments.mcp.register_tool("hello", {...}, hello_handler)

    # Start the MCP server
    result = await payments.mcp.start({
        "port": 5001,
        "planId": "your-plan-id",  # required
        "serverName": "my-mcp-server",
        # "agentId": "your-agent-id",  # optional (informational only)
        "version": "1.0.0",
        "description": "My MCP server with Nevermined payments"
    })

    print(f"Server running at: {result['info']['baseUrl']}")
    print(f"Tools: {result['info']['tools']}")

    # Server runs until stopped
    # To stop: await payments.mcp.stop()

asyncio.run(main())

Advanced API

For more control, use the advanced API:

Configure and Protect Handlers

# Configure shared options (planId required; agentId optional/informational)
payments.mcp.configure({
    "planId": "your-plan-id",
    "serverName": "my-mcp-server"
})

# Wrap a handler with paywall
async def my_handler(args):
    return {"result": "processed"}

protected_handler = payments.mcp.with_paywall(
    handler=my_handler,
    options={
        "kind": "tool",
        "name": "my_tool",
        "credits": 1
    }
)

Attach to Existing Server

from mcp.server import MCPServer

# Create your own MCP server
server = MCPServer()

# Attach payments integration
registrar = payments.mcp.attach(server)

# Register protected handlers
registrar.register_tool(
    name="hello",
    config={"description": "Hello tool"},
    handler=hello_handler,
    options={"credits": 1}
)

registrar.register_resource(
    name="config",
    template="data://{path}",
    config={"name": "Config"},
    handler=config_handler,
    options={"credits": 2}
)

Complete Example

import asyncio
from payments_py import Payments, PaymentOptions

# Initialize payments
payments = Payments.get_instance(
    PaymentOptions(nvm_api_key="nvm:your-key", environment="sandbox")
)

# Define handlers
async def analyze_code(args, context=None):
    """Analyze code for issues."""
    code = args.get("code", "")
    language = args.get("language", "python")

    # Your analysis logic here
    issues = analyze(code, language)

    return {
        "content": [{
            "type": "text",
            "text": f"Found {len(issues)} issues in {language} code."
        }]
    }

async def get_docs(uri, variables, context=None):
    """Return documentation."""
    topic = variables.get("topic", "general")

    return {
        "contents": [{
            "uri": str(uri),
            "mimeType": "text/markdown",
            "text": f"# Documentation for {topic}\n\nContent here..."
        }]
    }

async def code_review_prompt(args, context=None):
    """Generate code review prompt."""
    return {
        "messages": [{
            "role": "user",
            "content": {
                "type": "text",
                "text": "Please review the following code for best practices..."
            }
        }]
    }

# Register handlers
payments.mcp.register_tool(
    "analyze_code",
    {
        "description": "Analyzes code for potential issues",
        "inputSchema": {
            "type": "object",
            "properties": {
                "code": {"type": "string"},
                "language": {"type": "string", "default": "python"}
            },
            "required": ["code"]
        }
    },
    analyze_code,
    {"credits": 5}  # 5 credits per analysis
)

payments.mcp.register_resource(
    "docs://{topic}",
    {
        "name": "Documentation",
        "description": "Technical documentation",
        "mimeType": "text/markdown"
    },
    get_docs,
    {"credits": 1}
)

payments.mcp.register_prompt(
    "code_review",
    {
        "name": "Code Review",
        "description": "Generates a code review prompt"
    },
    code_review_prompt,
    {"credits": 2}
)

# Start server
async def main():
    result = await payments.mcp.start({
        "port": 5001,
        "planId": "plan-123",
        "serverName": "code-assistant-mcp",
        "version": "1.0.0"
    })

    print(f"MCP Server running at {result['info']['baseUrl']}")
    print(f"Tools: {result['info']['tools']}")
    print(f"Resources: {result['info']['resources']}")
    print(f"Prompts: {result['info']['prompts']}")

    # Keep running
    try:
        while True:
            await asyncio.sleep(1)
    except KeyboardInterrupt:
        await payments.mcp.stop()

asyncio.run(main())

Server Configuration

Option	Type	Required	Description
`port`	`int`	Yes	Server port
`planId`	`str`	Yes	Nevermined plan ID the server charges against
`serverName`	`str`	Yes	Human-readable name
`agentId`	`str`	No	Nevermined agent DID (informational; the facilitator resolves access from the plan + token)
`baseUrl`	`str`	No	Base URL (default: localhost)
`version`	`str`	No	Server version
`description`	`str`	No	Server description

Handler Options

Option	Type	Description
`credits`	`int` or `callable`	Credits to consume per call
`planId`	`str`	Per-handler plan ID override. A server-level `planId` (set via `configure`/`start`) is required; set this only to charge a different plan for this handler.
`maxAmount`	`int`	Max credits to verify during authentication (default: `1`)
`onRedeemError`	`str`	On post-execution settlement failure: `"ignore"` (default) returns the in-band payment error; `"propagate"` raises a JSON-RPC error. Tool content is always suppressed either way (a paid result is never delivered without settlement).

In-band x402 signaling (`_meta`)

The MCP transport follows the x402 v2 MCP transport specification: payments are signalled in band through the MCP tool-call machinery, not via HTTP status codes or headers. Request — payment payload. The client sends the x402 PaymentPayload as plain JSON in the tool-call request params under _meta["x402/payment"]. This is the payment channel — separate from session auth: the MCP session is an OAuth-protected resource, so the client must also send an Authorization: Bearer <access_token> header when opening the transport to establish the session (initialize returns 401 without it).

{
  "method": "tools/call",
  "params": {
    "name": "premium_tool",
    "arguments": { "...": "..." },
    "_meta": { "x402/payment": { "x402Version": 2, "accepted": { "...": "..." }, "payload": { "...": "..." } } }
  }
}

For backward compatibility the server still falls back to reading the access token from the Authorization: Bearer header when _meta["x402/payment"] is absent, but that path is deprecated under the x402 v2 MCP transport. Response — settlement receipt. On a successful paid call the SDK injects the settlement receipt under the spec key _meta["x402/payment-response"], alongside Nevermined-specific observability under the namespaced _meta["nevermined/credits"] key (not part of the x402 spec):

{
    "content": [{"type": "text", "text": "result"}],
    "_meta": {
        "x402/payment-response": {
            "success": True,
            "transaction": "0xabc...",
            "network": "eip155:84532",
            "payer": "0x123..."
        },
        "nevermined/credits": {
            "success": True,
            "txHash": "0xabc...",
            "creditsRedeemed": "5",
            "planId": "plan-123",
            "subscriberAddress": "0x123..."
        }
    }
}

Payment required. When the caller has not paid (or cannot be authorized), the tool returns an error tool result carrying the PaymentRequired object in both structuredContent (the object) and content[0].text (its JSON-stringified copy):

{
    "isError": True,
    "structuredContent": {
        "x402Version": 2,
        "error": "payment required",
        "resource": { "url": "mcp://my-server/tools/premium_tool", "...": "..." },
        "accepts": [ { "scheme": "nvm:erc4337", "planId": "plan-123", "...": "..." } ]
    },
    "content": [{"type": "text", "text": "{\"x402Version\": 2, ...}"}]
}

Settlement failure after execution. If settlement fails after the tool has already executed, the server returns the same payment-required error result and suppresses the tool’s content — a paid result is never delivered without payment landing.

Note on onRedeemError. Under the in-band MCP transport, content is always suppressed when post-execution settlement fails — even with the default onRedeemError: "ignore" — because the x402 v2 spec forbids delivering a paid result without settlement. onRedeemError no longer controls whether content is returned; it now only affects the kind of error surfaced: "ignore" yields the in-band payment-required error result, while "propagate" raises a JSON-RPC misconfiguration error instead.

`nevermined/credits` field	Type	Description
`success`	`bool`	Whether credit redemption succeeded
`txHash`	`str` or `None`	Blockchain transaction hash (only on success)
`creditsRedeemed`	`str`	Number of credits burned (`"0"` on failure)
`planId`	`str`	Plan used for the operation
`subscriberAddress`	`str`	Subscriber’s wallet address
`errorReason`	`str`	Error message (only on failure)

Endpoints

The MCP server exposes:

/.well-known/oauth-authorization-server - OAuth 2.1 discovery
/.well-known/oauth-protected-resource - Resource metadata
/.well-known/oauth-protected-resource/mcp - MCP-specific protected resource metadata
/register - Client registration
/mcp - MCP protocol endpoint (POST/GET/DELETE)
/health - Health check

OAuth `401` vs. payment-required

OAuth and x402 payment-required live at different layers, so they never collide:

Layer	Signal	Meaning
HTTP transport	`401 Unauthorized` + `WWW-Authenticate: Bearer` (OAuth 2.1)	The request is not authenticated; follow OAuth discovery to obtain a token.
MCP tool call	tool result with `isError: true` + `PaymentRequired` in `structuredContent`	The caller is authenticated but has not paid for this tool.

Because payment-required is signalled in band as a tool result (not as an HTTP 402), there is no clash with the OAuth 401 challenge and no need to special-case the /mcp status code. The /mcp endpoint keeps the standard OAuth 401 behavior; payment is negotiated entirely through the tool-call _meta / tool-result mechanism described above. x402 discovery is therefore implicit on the first tool call: a client that has not paid receives the PaymentRequired object (with its accepts array) in the error tool result and pays on the next call. There is no /.well-known/x402-payment endpoint.

Overview

MCP Integration API

Simplified API (Recommended)

Register a Tool

Register a Resource

Register a Prompt

Start the Server

Advanced API

Configure and Protect Handlers

Attach to Existing Server

Complete Example

Server Configuration

Handler Options

In-band x402 signaling (`_meta`)

Endpoints

OAuth `401` vs. payment-required

Next Steps

A2A Integration

x402 Protocol

​Overview

​MCP Integration API

​Simplified API (Recommended)

​Register a Tool

​Register a Resource

​Register a Prompt

​Start the Server

​Advanced API

​Configure and Protect Handlers

​Attach to Existing Server

​Complete Example

​Server Configuration

​Handler Options

​In-band x402 signaling (_meta)

​Endpoints

​OAuth 401 vs. payment-required

​Next Steps

A2A Integration

x402 Protocol

Overview

MCP Integration API

Simplified API (Recommended)

Register a Tool

Register a Resource

Register a Prompt

Start the Server

Advanced API

Configure and Protect Handlers

Attach to Existing Server

Complete Example

Server Configuration

Handler Options

In-band x402 signaling (`_meta`)

Endpoints

OAuth `401` vs. payment-required

Next Steps