Are you building with an LLM?If you are using an AI assistant for development, you can provide it with a comprehensive context file to streamline the integration process.Click here to view the raw context file. Simply copy its contents and paste them into your LLM’s input as a knowledge base.
- Paywall Protection: Wrap your handlers with
withPaywall
to automatically verifyAuthorization
tokens and check for valid subscriptions. - Credit Burning: Automatically burn credits after a successful API call, with support for both fixed and dynamic costs.
- Declarative Registration: Use the
attach
method to register and protect your tools in a single, clean step. - Framework Agnostic: Works with both high-level servers (like the official TypeScript SDK’s
McpServer
or Python’sFastMCP
) and custom low-level ASGI/Express routers.
What is MCP?
As Large Language Models (LLMs) and AI agents become more sophisticated, their greatest limitation is their isolation. By default, they lack access to real-time information, private data sources, or the ability to perform actions in the outside world. The Model Context Protocol (MCP) was designed to solve this problem by creating a standardized communication layer for AI. Think of MCP as a universal language that allows any AI agent to ask a server, “What can you do?” and “How can I use your capabilities?”. It turns a closed-off model into an agent that can interact with the world through a secure and discoverable interface. An MCP server essentially publishes a “menu” of its services, which can include:- Tools: These are concrete actions the agent can request, like sending an email, querying a database, or fetching a weather forecast. The agent provides specific arguments (e.g.,
city="Paris"
) and the server executes the action. - Resources: These are stable pointers to data, identified by a URI. While a tool call might give a human-readable summary, a resource link (
weather://today/Paris
) provides the raw, structured data (like a JSON object) that an agent can parse and use for further tasks. - Prompts: These are pre-defined templates that help guide an agent’s behavior, ensuring it requests information in the correct format or follows a specific interaction pattern.
Why integrate MCP with Nevermined Payments Library?
While MCP provides a powerful standard for what an AI agent can do, it doesn’t specify who is allowed to do it or how those services are paid for. This is where Nevermined Payments Library comes in. By integrating Nevermined, you can transform your open MCP server into a secure, monetizable platform. The core idea is to place a “paywall” in front of your MCP handlers. This paywall acts as a gatekeeper, intercepting every incoming request to a tool, resource, or prompt. Before executing your logic, it checks the user’sAuthorization
header to verify they have a valid subscription and sufficient credits through the Nevermined protocol. If they don’t, the request is blocked. If they do, the request proceeds, and after your handler successfully completes, the paywall automatically deducts the configured number of credits.
This integration allows you to build a sustainable business model around your AI services. You can offer different subscription tiers (plans), charge dynamically based on usage, and maintain a complete audit trail of every transaction, all without cluttering your core application logic with complex payment code.
Step-by-step Tutorial
In this tutorial, we will embark on a practical journey to build a secure, monetizable MCP server. Our starting point will be a standard, unprotected server—a common scenario for developers who have already created useful AI tools and now wish to commercialize them. From there, we will layer on the security and monetization capabilities of Nevermined Payments Library step by step.0) Requirements & Installation
- Node.js >= 18
- MCP SDK (
@modelcontextprotocol/sdk
) @nevermined-io/payments
(Nevermined SDK)- Express.js
1) Create a Minimal MCP Server
First, let’s create a basic MCP server without any paywall to ensure the core setup is working.This server uses the official MCP SDK and exposes a single tool,
weather.today
.2) Initialize Nevermined Payments
Next, initialize the Nevermined Payments SDK. This requires your builder/agent owner API key and the environment (sandbox
or live
).
3) Protect Handlers with a Paywall
ThewithPaywall
(TS) or with_paywall
(PY) decorator is the core of the integration. It wraps your business logic, checks for authentication, and burns credits.
First, define your handler. It should contain only your business logic, returning a standard MCP content
object.
The
extra
object, containing request headers, is passed automatically by the MCP server to the handler. The paywall uses this to extract the Authorization
token.4) Dynamic Credit Calculation
For flexible pricing, provide a function to thecredits
option. It receives a context object (ctx
) with request args
, the handler’s result
, and extra
metadata.
5) Alternative: Declarative Registration with attach
While withPaywall
is useful, it can be repetitive. The attach
method provides a more streamlined alternative by combining registration and protection into a single call. It takes your server instance and returns a registrar object with protected registerTool
, registerResource
, and registerPrompt
methods.
6) Alternative: Custom Low-Level Server
If you prefer full control, you can implement a low-level JSON-RPC router. You are responsible for parsing the request, routing it, and manually passing anextra
object (containing request headers) to the protected handler.
This example shows a minimal router using Express.js.
7) Client: Getting Access & Calling
On the client side, the process is to get a NeverminedaccessToken
and include it in the Authorization
header of every MCP request.
Error Handling
- No token / Invalid token / Insufficient credits → JSON-RPC error
-32003
- Other server errors → JSON-RPC error
-32002
Full Code Examples
You can find the complete working examples used in this tutorial in the following GitHub repositories:- Python: nevermined-io/weather-mcp-demo-py
- TypeScript: nevermined-io/weather-mcp-demo