Prerequisites and Versions
Before getting hands-on, here’s what you need:
- Node.js: v18.x or later (LTS recommended)
- npm: v9.x or later (comes with Node.js)
- Git: for cloning repos
- Basic Base Network RPC access: An RPC endpoint (public or private) for Base mainnet or testnet
- An on-chain data indexing tool or service: Could be a light indexer or The Graph compatible setup
Libraries & tools covered here:
| Component |
Version Used |
Notes |
| MCP Server NPM package |
@mcp/[email protected] |
Early release; APIs may evolve |
| Base Network RPC |
Mainnet RPC endpoint |
Replace with your provider URL |
| Indexing client |
Postgres-backed indexing |
Example built on blockchain-data-sources-for-mcp |
The MCP server is still early-stage. API or config flags may change, so double-check the @mcp/server docs if you hit weird errors.
Installing the MCP Server NPM Package
Start by creating a new project directory and initializing a Node.js project:
mkdir base-mcp-server && cd base-mcp-server
npm init -y
Next, install the MCP server package:
npm install @mcp/server
This package includes the core server logic and CLI to launch an MCP endpoint supporting Base-compatible messaging.
Confirm installation:
npx mcp-server --version
You should see output like:
@mcp/server/0.3.2
If not, check your npm logs or Node version.
Configuring the MCP Server for the Base Network
You need to provide at least the following to configure your MCP server:
- RPC URL for Base (mainnet or testnet)
- On-chain contract addresses (MCP payment contracts on Base)
- Indexing database connection
Create a config.json (or config.js) file in your project root with this minimal config:
{
"chain": "base",
"rpcUrl": "https://base-mainnet.rpc.provider",
"contracts": {
"payment": "0xYourPaymentContractAddress"
},
"indexing": {
"type": "postgres",
"connectionString": "postgres://user:pass@localhost:5432/mcp"
},
"server": {
"port": 4000
}
}
Replace the rpcUrl and contract address with actual deployed Base MCP contracts and your RPC provider endpoint.
The Postgres setup is a common choice for on-chain data indexing. For the bare minimum, your tables should capture these:
- Agent requests
- Payment receipts
- Event logs from MCP contracts
This example config sets your server to listen on port 4000.
Pro tip: Keep your private keys and secrets out of this file if you add key management; environment variables are safer.
Connecting On-Chain Data Indexing
The MCP server’s main duty is extracting relevant on-chain data and serving it to your AI agents or clients.
You can hook into existing indexing frameworks or write a simple event listener using ethers.js. Here's a minimal script snippet showing how you might sync payment events:
import { ethers } from 'ethers';
import { Pool } from 'pg';
const provider = new ethers.providers.JsonRpcProvider(process.env.RPC_URL);
const paymentContract = new ethers.Contract(
process.env.PAYMENT_CONTRACT,
[
'event PaymentMade(address indexed from, uint256 amount, uint256 requestId)'
],
provider
);
const pool = new Pool({ connectionString: process.env.DB_CONNECTION });
paymentContract.on('PaymentMade', async (from, amount, requestId) => {
await pool.query(
'INSERT INTO payments (from_address, amount, request_id) VALUES ($1, $2, $3)',
[from, amount.toString(), requestId.toNumber()]
);
console.log('Payment recorded:', { from, amount: amount.toString(), requestId: requestId.toNumber() });
});
console.log('Listening to Base MCP PaymentMade events...');
Run this script alongside your MCP server or integrate the event subscription directly inside the server. The key: keep your on-chain data state synced and queryable for the MCP request pipeline.
If you prefer a ready-made solution, explore the blockchain-data-sources-for-mcp page for setups including The Graph or optimized indexers.
Deploying Your MCP Server Node
With config and indexing in place, launch your server:
npx mcp-server --config ./config.json
Expect log output like:
[MCP Server] Starting on port 4000
[MCP Server] Connected to Base RPC at https://base-mainnet.rpc.provider
[MCP Server] Indexer connected to PostgreSQL
[MCP Server] Listening for MCP agent requests...
You can now query the HTTP endpoint or websocket (check docs) to process MCP agent requests, payments, and model contexts.
For production, consider dockerizing this setup or using a process manager like PM2:
pm install -g pm2
pm run build
pm start # your script to launch MCP server
pm2 start npm --name mcp-server -- start
Also, set NODE_ENV=production and secure your server with TLS for endpoints exposed externally.
Security Best Practices
MCP and Base agents imply funds being moved and potentially autonomous execution. So here’s a checklist from my experience to keep your server robust:
- Session keys & spending limits: Never give the server full control of agent wallets. Use scoped session keys with explicit spending caps. See mcp-wallet-integration for details.
- Database security: Use least privilege for your Postgres user; avoid SQL injection by using parameterized queries as shown above.
- RPC endpoint trust: Avoid relying on public RPCs for sensitive flows; a private Base archive node is better for consistent event indexing.
- API rate limits and request throttling: Prevent DoS by limiting inbound MCP calls per client.
- Keep secrets out of code & configs: Use environment variables or secure vaults.
From a contract perspective, watch out for unsafe payment patterns flagged by static analysis tools like Slither or Aderyn. Lock down approvals and avoid unlimited token allowances.
For a deep dive on these topics, see mcp-server-security-best-practices.
Troubleshooting Common Issues
Error: RPC connection failed
- Check your RPC URL and network connectivity.
- Verify rate limits on your RPC provider.
Database connection refused
- Confirm your Postgres is running and reachable.
- Test credentials independently.
Event listener missing payments
- Check if your node is an archive/full node.
- Ensure your event filters match deployed contract addresses.
MCP requests timeout
- Debug whether indexing is lagging or the server is overloaded.
npm run scripts don’t find mcp-server commands
- Double-check installation or try global install to test commands.
If stuck, logs are your friend: increase logging verbosity by passing --verbose.
For more errors and fixes, explore mcp-server-troubleshooting.
Conclusion and Next Steps
Building a Base MCP server isn't trivial, but with this step-by-step foundation, you can bootstrap a working node to interface your AI agents with the Base network's on-chain ecosystem.
What I’ve found is that real projects demand iteration — adding payment protocol support, expanding indexing coverage, or integrating session key management per mcp-wallet-integration.
Next, consider exploring:
And if you’d like a Python-based MCP server or integration example, check how-to-build-web3-mcp-server-python.
Happy building — with careful setup, your Base MCP server will be a reliable backbone enabling decentralized AI and payment processing.
