MCP Servers: The Bridge Between AI Agents and Real-World Services
The Model Context Protocol (MCP) is a standardized way for AI agents to interact with external services using a consistent interface. Unlike traditional REST APIs, MCP provides a discoverable, tool-based approach that works seamlessly with any LLM (Large Language Model) like Claude or GPT.
In this explainer, we’ll explore how MCP servers enable AI agents to perform real-world tasks—using the flat.cash MCP server as a working example. This server exposes eight tools for managing a decentralized savings protocol, all accessible via JSON-RPC over HTTP.
What Is an MCP Server?
An MCP server is a lightweight service that exposes a set of tools (functions) to AI agents. Instead of requiring developers to write custom API clients, MCP provides a standardized way for LLMs to:
- Discover available tools (via a manifest).
- Call tools dynamically (using JSON-RPC).
- Receive structured responses (in JSON).
This makes MCP ideal for AI agents that need to interact with external systems—whether it’s querying a database, processing payments, or fetching real-time data.
The flat.cash MCP Server: A Real-World Example
The flat.cash MCP server provides access to a decentralized savings protocol called SAVE. It exposes eight tools:
| Tool | Description |
|---|---|
flat_register |
Register a new user in the SAVE protocol |
flat_verify |
Verify a user’s identity |
flat_auth |
Authenticate a user for transactions |
flat_read |
Read user data (balance, savings, etc.) |
flat_earn |
Earn interest on savings |
flat_pay |
Make payments or transfers |
flat_admin |
Admin-only functions (e.g., pausing contracts) |
flat_cash_delivery |
Request cash delivery (for on/off-ramp) |
All tools are accessible via a single HTTP endpoint:
POST https://flat.cash/api/mcp
How an AI Agent Uses MCP: A Step-by-Step Example
Let’s walk through a scenario where an AI agent helps a user register, earn SAVE, and query their balance—all via MCP.
Step 1: Discover Available Tools
The agent first fetches the MCP server’s manifest to see what tools are available. The manifest is typically served at:
https://flat.cash/api/mcp/manifest
Example response (simplified):
{
"name": "flat.cash",
"version": "1.0.0",
"description": "MCP server for the SAVE savings protocol",
"tools": [
{
"name": "flat_register",
"description": "Register a new user in the SAVE protocol",
"inputSchema": {
"type": "object",
"properties": {
"wallet_address": { "type": "string" }
}
}
},
{
"name": "flat_earn",
"description": "Earn interest on savings",
"inputSchema": {
"type": "object",
"properties": {
"amount": { "type": "number" }
}
}
},
{
"name": "flat_read",
"description": "Read user data (balance, savings, etc.)",
"inputSchema": {
"type": "object",
"properties": {
"user_id": { "type": "string" }
}
}
}
]
}
Step 2: Register a New User
The agent calls flat_register with a wallet address:
{
"jsonrpc": "2.0",
"method": "callTool",
"params": {
"name": "flat_register",
"arguments": {
"wallet_address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
}
},
"id": 1
}
The MCP server processes the request and returns:
{
"jsonrpc": "2.0",
"result": {
"status": "success",
"user_id": "user_12345",
"message": "User registered successfully"
},
"id": 1
}
Step 3: Earn SAVE Interest
The user wants to earn interest, so the agent calls flat_earn:
{
"jsonrpc": "2.0",
"method": "callTool",
"params": {
"name": "flat_earn",
"arguments": {
"amount": 1000
}
},
"id": 2
}
The server responds:
{
"jsonrpc": "2.0",
"result": {
"status": "success",
"earned_amount": 1000,
"interest_rate": "5%",
"new_balance": 1050
},
"id": 2
}
Step 4: Query User Balance
Finally, the agent checks the user’s balance using flat_read:
{
"jsonrpc": "2.0",
"method": "callTool",
"params": {
"name": "flat_read",
"arguments": {
"user_id": "user_12345"
}
},
"id": 3
}
Response:
{
"jsonrpc": "2.0",
"result": {
"balance": 1050,
"savings": 1000,
"interest_earned": 50,
"last_updated": "2024-05-20T12:00:00Z"
},
"id": 3
}
MCP vs. REST APIs: Key Differences
| Feature | MCP | REST API |
|---|---|---|
| Discovery | Tools are self-describing (via manifest) | Requires external documentation |
| Tool Usage | Dynamic, agent-driven calls | Predefined endpoints |
| Standardization | JSON-RPC over HTTP (universal) | Varies by implementation |
| LLM Integration | Native support (Claude, GPT, etc.) | Requires custom API clients |
| Flexibility | Agent can call any tool dynamically | Fixed endpoints |
MCP is better suited for AI agents because:
- No need to hardcode API calls—the agent discovers tools at runtime.
- Structured responses make it easier for LLMs to parse results.
- Works with any LLM (no vendor lock-in).
Limitations of MCP
While MCP is powerful, it has some limitations:
- Not all APIs support MCP yet—most services still use REST or GraphQL.
- Performance overhead—JSON-RPC adds slight latency compared to raw REST.
- Tool discovery requires standardization—not all MCP servers follow best practices.
For now, MCP is best for AI-native applications where dynamic tool usage is critical.
Getting Started with flat.cash MCP
To explore the flat.cash MCP server:
- Read the full documentation: docs.flat.cash
-
Test the MCP endpoint:
POST https://flat.cash/api/mcp -
Experiment with tools using
curlor a tool like Postman.
Example curl request:
curl -X POST https://flat.cash/api/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "callTool",
"params": {
"name": "flat_register",
"arguments": {
"wallet_address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
}
},
"id": 1
}'
Conclusion
MCP servers like flat.cash are revolutionizing how AI agents interact with real-world services. By providing a standardized, tool-based interface, MCP eliminates the need for custom API clients and makes it easier for LLMs to perform complex tasks.
For developers building AI-native applications, MCP is a game-changer—but adoption is still early. If you're working on an AI agent that needs to interact with external systems, consider integrating MCP for a more flexible and scalable solution.
Further reading:
Top comments (0)