Skip to main content

​
Model Context Protocol (MCP)

The Model Context Protocol is an open standard that enables AI assistants to securely connect to external data sources and tools.

​
Protocol Overview

MCP provides a standardized way for AI assistants to:

Access Tools

Execute functions and retrieve data from external systems

Exchange Data

Send structured requests and receive formatted responses

Maintain Context

Preserve conversation state and execution history

Ensure Security

Control access and validate requests

​
Architecture

​
Communication Flow

​
Components

​
MCP Client

The client runs within the AI assistant environment:
  • Handles user interactions
  • Formats tool requests according to MCP spec
  • Parses server responses
  • Manages connection lifecycle

​
MCP Server

The server bridges AI assistants and external services:
  • Exposes available tools and capabilities
  • Validates incoming requests
  • Transforms requests to API calls
  • Formats responses for AI consumption
  • Handles errors and retries

​
Protocol Features

​
Tool Discovery

Servers advertise their capabilities: 
{
  "tools": [
    {
      "name": "fred_search",
      "description": "Search FRED economic data series",
      "inputSchema": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string",
            "description": "Search terms"
          }
        },
        "required": ["query"]
      }
    }
  ]
}

​
Request Format

Tool calls follow a standardized structure: 
{
  "method": "tools/call",
  "params": {
    "name": "fred_search",
    "arguments": {
      "query": "unemployment rate",
      "limit": 10
    }
  }
}

​
Response Format

Servers return structured data: 
{
  "content": [
    {
      "type": "text",
      "text": "Found 10 series matching query"
    },
    {
      "type": "resource",
      "resource": {
        "uri": "fred://series/UNRATE",
        "name": "Unemployment Rate",
        "mimeType": "application/json"
      }
    }
  ]
}

​
Connection Types

​
Standard I/O (stdio)

Direct process communication:
  • Server runs as subprocess
  • Uses stdin/stdout for messaging
  • Lowest latency
  • Most secure (no network exposure)
Configuration: 
{
  "mcpServers": {
    "fred": {
      "command": "npx",
      "args": ["-y", "fred-mcp-server"],
      "env": {
        "FRED_API_KEY": "your-api-key"
      }
    }
  }
}

​
HTTP/SSE

Network-based communication:
  • Server runs as web service
  • Uses Server-Sent Events for streaming
  • Supports remote deployment
  • Requires network configuration

​
Security Model

​
Authentication

  • Keys stored in environment variables
  • Never exposed in requests/responses
  • Can be rotated without code changes
  • Schema validation on all inputs
  • Type checking and sanitization
  • Rate limiting enforcement
  • Server runs in isolated process
  • Limited filesystem access
  • Network access controlled

​
Data Privacy

MCP ensures:
  • No data logged without consent
  • Responses contain only requested data
  • Secure transmission between components
  • API keys never appear in responses

​
Error Handling

​
Error Types

CodeTypeDescription
-32700Parse ErrorInvalid JSON received
-32600Invalid RequestMalformed request structure
-32601Method Not FoundUnknown tool requested
-32602Invalid ParamsBad parameter values
-32603Internal ErrorServer-side failure

​
Error Response Format

{
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": {
      "field": "query",
      "reason": "Required parameter missing"
    }
  }
}

​
Performance Considerations

​
Request Optimization

1

Batch Related Calls

Group similar requests when possible
2

Use Streaming

For large datasets, stream results incrementally
3

Limit Data Requests

Request only necessary date ranges and series
4

Implement Timeouts

Set reasonable limits for long-running operations

​
Connection Management

  • Reuse server processes
  • Implement connection pooling
  • Handle graceful shutdowns
  • Monitor resource usage

​
MCP Specification

The protocol follows JSON-RPC 2.0 with extensions:

​
Core Methods

MethodPurpose
initializeEstablish connection
tools/listDiscover available tools
tools/callExecute tool
resources/listList available resources
resources/readAccess resource content
prompts/listGet prompt templates

​
Lifecycle

​
Best Practices

​
Server Development

Key principles:
  • Implement comprehensive error handling
  • Validate all inputs thoroughly
  • Provide clear, descriptive tool schemas
  • Return actionable error messages
  • Log appropriately for debugging

​
Client Integration

Common pitfalls:
  • Not handling connection failures
  • Ignoring timeout scenarios
  • Poor error message presentation
  • Inadequate retry logic

​
FRED MCP Implementation

This server implements MCP to provide:

​
Tools

  1. fred_search: Full-text search across all series
  2. fred_browse: Navigate category hierarchy
  3. fred_get_series: Retrieve time series data

​
Resources

  • Series metadata
  • Category information
  • Release schedules

​
Prompts

  • Economic analysis templates
  • Data exploration guides
  • Research question frameworks

​
Next Steps

API Tools

Explore available tools

FRED Data

Understand data structure

Authentication

Setup API access

Examples

See usage examples