MCP Servers Guide

MCP Servers Comprehensive Guide

MCP (Model Context Protocol) is the open standard for connecting AI agents to tools. This guide covers everything from architecture to deployment.

What Is MCP?

AI Agent (Claude, GPT, etc.)
    │
    ▼
MCP Client (built into host app)
    │
    ▼
MCP Server (your tool/service)
    │
    ├── Tools (functions the agent can call)
    ├── Resources (data the agent can read)
    └── Prompts (templates for the agent)

Core Primitives

Tools

Functions the agent can execute:

server.tool('getTokenPrice', {
  description: 'Get the current price of a cryptocurrency',
  parameters: z.object({
    symbol: z.string().describe('Token symbol (e.g., SPA, ETH)'),
    currency: z.string().default('usd').describe('Target currency')
  }),
  handler: async ({ symbol, currency }) => {
    const price = await fetchPrice(symbol, currency);
    return { content: [{ type: 'text', text: `${symbol}: $${price}` }] };
  }
});

Resources

Data the agent can read:

server.resource('portfolio', {
  description: 'User DeFi portfolio',
  uri: 'portfolio://current',
  handler: async () => {
    const portfolio = await getPortfolio();
    return { content: [{ type: 'text', text: JSON.stringify(portfolio) }] };
  }
});

Prompts

Templates for the agent:

server.prompt('defi-analysis', {
  description: 'Analyze a DeFi protocol',
  arguments: [{ name: 'protocol', description: 'Protocol name' }],
  handler: ({ protocol }) => ({
    messages: [{
      role: 'user',
      content: `Analyze the DeFi protocol "${protocol}" covering TVL, APY, risks, and team.`
    }]
  })
});

Transport Types

stdio Setup

{
  "mcpServers": {
    "my-tool": {
      "command": "npx",
      "args": ["@my/mcp-server"]
    }
  }
}

SSE Setup

{
  "mcpServers": {
    "my-tool": {
      "url": "https://mcp.example.com/sse"
    }
  }
}

Building an MCP Server

TypeScript (Recommended)

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const server = new McpServer({
  name: 'sperax-defi',
  version: '1.0.0',
  description: 'Sperax DeFi tools'
});

// Add tools
server.tool('getUSdsAPY', {
  description: 'Get current USDs auto-yield APY',
  handler: async () => ({
    content: [{ type: 'text', text: 'USDs APY: 7.2%' }]
  })
});

// Start server
const transport = new StdioServerTransport();
await server.connect(transport);

Python

from mcp.server import Server
from mcp.server.stdio import stdio_server

server = Server("sperax-defi")

@server.tool("getUSdsAPY")
async def get_usds_apy():
    """Get current USDs auto-yield APY"""
    return "USDs APY: 7.2%"

async def main():
    async with stdio_server() as (read, write):
        await server.run(read, write)

Security Best Practices

Popular MCP Servers

Links

• MCP Spec: https://modelcontextprotocol.io
• SDK (TypeScript): https://github.com/modelcontextprotocol/typescript-sdk
• SDK (Python): https://github.com/modelcontextprotocol/python-sdk
• MCP Servers GitHub: https://github.com/nirholas/mcp-servers
• SperaxOS: https://app.sperax.io