API Documentation

MCP Financial API Documentation

Welcome to the official documentation for the Model Context Protocol (MCP) Financial API. This guide will help you integrate our financial analysis tools and stock market data into your applications or AI assistants.

Introduction

The MCP Financial API is designed to provide advanced financial analysis capabilities to AI assistants, apps, and LLMs through a simple, unified interface using the Model Context Protocol (MCP). Our API supports financial metrics calculation, real-time stock market data, time series analysis, portfolio optimization, and document processing with semantic search.

Authentication

All API requests require an API key for authentication. You can generate API keys in your dashboard after subscribing to our service.

Include your API key in all requests using one of these methods:

HTTP Header (preferred)
X-API-Key: your_api_key
Query Parameter
https://mcpfinancials.com/api/v1/mcp?api_key=your_api_key

Rate Limits

API requests are subject to rate limiting based on your subscription plan:

  • Free Plan: 100 API requests total (lifetime limit)
  • Pro Plan: 10,000 API requests per month
  • Enterprise Plan: Custom limits based on your needs

Pro Plan limits are reset monthly. Free Plan limits are fixed at 100 total requests. If you exceed your rate limit, requests will return a 429 Too Many Requests response until the limit resets or you upgrade your plan.

Error Handling

The API uses standard HTTP status codes to indicate the success or failure of a request. In general:

  • 2xx: Success
  • 4xx: Client error (invalid request, authentication, etc.)
  • 5xx: Server error

Error responses include a JSON object with an error message:

{
  "error": "Invalid API key or rate limit exceeded"
}

MCP Protocol

The Model Context Protocol (MCP) provides a standardized way for AI models to interact with external services. Our API implements this protocol to enable AI assistants to access financial analysis capabilities through JSON-RPC calls.

How MCP Works

What's happening under the hood
  1. User asks a question - The client sends the query to the AI model (OpenAI)
  2. AI analyzes available tools - OpenAI analyzes the tools and decides which one(s) to use
  3. Tool execution - The server executes the chosen tool(s) through the MCP JSON-RPC interface
  4. Results processing - Results are sent back to OpenAI
  5. Response formulation - OpenAI formulates a natural language response incorporating the results
  6. Display - The final response is displayed to the user

JSON-RPC Interface

Our MCP implementation uses JSON-RPC to standardize communication between AI models and financial tools. This allows AI assistants to discover and invoke financial calculations dynamically.

POST /jsonrpc

This endpoint handles all JSON-RPC requests for financial calculations and analysis.

Request Body:
{
  "jsonrpc": "2.0",
  "method": "calculate.financialRatio",
  "params": {
    "ratio_type": "current_ratio",
    "current_assets": 5000,
    "current_liabilities": 2000
  },
  "id": "1"
}
Response:
{
  "jsonrpc": "2.0",
  "result": {
    "ratio": 2.5,
    "ratio_type": "current_ratio",
    "numerator": 5000,
    "denominator": 2000
  },
  "id": "1"
}

Production Endpoints

For seamless integration with the production MCP API at mcpfinancials.com, the following endpoints are available to proxy your requests directly to the live service.

When integrating with the production API directly, use the URL above (not the proxy URLs below which are specific to this application).

Python Integration Example:
import os
import requests

# Your API key from environment variables
MCP_API = os.getenv("MCP_API")

# Production MCP API URL
MCP_URL = "https://mcpfinancials.com/api/jsonrpc"

# Example request
headers = {
    "Content-Type": "application/json",
    "X-API-Key": MCP_API
}
payload = {
    "jsonrpc": "2.0",
    "method": "finance.calculateRatio",
    "params": {
        "ratio_type": "debt_to_equity",
        "numerator": 1000,
        "denominator": 500
    },
    "id": "example-1"
}

# Send the request
response = requests.post(MCP_URL, json=payload, headers=headers)
result = response.json()
print(result)
POST /production/mcp-proxy

Public proxy endpoint that forwards JSON-RPC requests to the production MCP API. No authentication required.

Request Body:
{
  "jsonrpc": "2.0",
  "method": "discover.getAvailableMetrics",
  "params": {},
  "id": "test-1"
}
Response:
{
  "jsonrpc": "2.0",
  "result": {
    "metrics": [
      {
        "id": "current_ratio",
        "name": "Current Ratio",
        "category": "liquidity"
      },
      // Additional metrics...
    ]
  },
  "id": "test-1"
}
POST /production/secure-mcp-proxy

Authenticated proxy endpoint that forwards JSON-RPC requests to the production MCP API. Requires your API key.

Headers:
Content-Type: application/json
X-API-Key: your_api_key
Request Body:
{
  "jsonrpc": "2.0",
  "method": "finance.calculateRatio",
  "params": {
    "ratio_type": "debt_to_equity",
    "numerator": 1000,
    "denominator": 500
  },
  "id": "test-2"
}
Response:
{
  "jsonrpc": "2.0",
  "result": {
    "ratio": 2.0,
    "ratio_type": "debt_to_equity",
    "interpretation": "The company has 2.0 times more debt than equity, which may indicate higher financial risk.",
    "numerator": 1000,
    "denominator": 500
  },
  "id": "test-2"
}
GET /production/endpoints-info

Get information about available production endpoints, including example requests.

Response:
{
  "endpoints": [
    {
      "url": "/production/mcp-proxy",
      "method": "POST",
      "authentication": "None",
      "description": "Proxy to production MCP API at mcpfinancials.com",
      "example": {
        "jsonrpc": "2.0",
        "method": "discover.getAvailableMetrics",
        "params": {},
        "id": "test-1"
      }
    },
    {
      "url": "/production/secure-mcp-proxy",
      "method": "POST",
      "authentication": "API Key (Header: X-API-Key)",
      "description": "Authenticated proxy to production MCP API at mcpfinancials.com",
      "example": {
        "jsonrpc": "2.0",
        "method": "finance.calculateRatio",
        "params": {
          "ratio_type": "debt_to_equity",
          "numerator": 1000,
          "denominator": 500
        },
        "id": "test-2"
      }
    }
  ],
  "production_url": "https://mcpfinancials.com/api/jsonrpc"
}

MCP Direct API

POST /api/v1/mcp

Legacy endpoint for direct MCP requests (JSON-RPC is preferred).

Request Body:
{
  "type": "api",
  "action": "get",
  "parameters": {
    "integration": "financial",
    "query": "calculate_financial_ratios",
    "data": {
      "current_assets": 100000,
      "current_liabilities": 50000,
      "total_debt": 120000,
      "total_equity": 200000
    }
  }
}
Response:
{
  "success": true,
  "data": {
    "current_ratio": 2.0,
    "debt_to_equity": 0.6
  }
}

Financial API

The Financial API provides access to various financial calculations, metrics, and analysis tools.

Financial Metrics

Calculate financial ratios and metrics for analysis:

POST /api/v1/mcp

Calculate financial ratios based on the provided data.

Request Body:
{
  "type": "api",
  "action": "get",
  "parameters": {
    "integration": "financial",
    "query": "calculate_financial_ratios",
    "data": {
      "current_assets": 100000,
      "current_liabilities": 50000,
      "total_debt": 120000,
      "total_equity": 200000,
      "revenue": 500000,
      "net_income": 75000
    }
  }
}
Response:
{
  "success": true,
  "data": {
    "current_ratio": 2.0,
    "debt_to_equity": 0.6,
    "profit_margin": 0.15,
    "return_on_equity": 0.375
  }
}

Stock Market Data

Access real-time and historical stock market data via our Marketstack API integration:

POST /jsonrpc

Get current or historical stock prices for one or more ticker symbols.

Request Body:
{
  "jsonrpc": "2.0",
  "method": "marketstack.getEodData",
  "params": {
    "symbols": "AAPL,MSFT",
    "date": "2025-01-15"  // Optional, omit for latest data
  },
  "id": "stock-1"
}
Response:
{
  "jsonrpc": "2.0",
  "result": {
    "data": [
      {
        "symbol": "AAPL",
        "exchange": "NASDAQ",
        "date": "2025-01-15T00:00:00.000Z",
        "open": 185.82,
        "high": 187.67,
        "low": 184.25,
        "close": 186.19,
        "volume": 51427300
      },
      {
        "symbol": "MSFT",
        "exchange": "NASDAQ",
        "date": "2025-01-15T00:00:00.000Z",
        "open": 398.56,
        "high": 401.23,
        "low": 395.68,
        "close": 399.98,
        "volume": 25842700
      }
    ]
  },
  "id": "stock-1"
}
POST /jsonrpc

Get historical stock data for one or more ticker symbols within a date range.

Request Body:
{
  "jsonrpc": "2.0",
  "method": "marketstack.getHistoricalData",
  "params": {
    "symbols": "TSLA",
    "date_from": "2025-01-01",
    "date_to": "2025-01-31",
    "sort": "ASC"  // Optional, default is "DESC"
  },
  "id": "stock-2"
}
Response:
{
  "jsonrpc": "2.0",
  "result": {
    "data": [
      {
        "symbol": "TSLA",
        "exchange": "NASDAQ",
        "date": "2025-01-02T00:00:00.000Z",
        "open": 242.17,
        "high": 245.33,
        "low": 240.56,
        "close": 243.42,
        "volume": 18935600
      },
      // Additional days of data...
    ],
    "analysis": {
      "TSLA": {
        "start_price": 242.17,
        "end_price": 256.89,
        "price_change": 14.72,
        "percent_change": 6.08,
        "max_price": 262.36,
        "min_price": 240.56,
        "trend": "up",
        "data_points": 21
      }
    }
  },
  "id": "stock-2"
}
POST /jsonrpc

Calculate and analyze stock performance metrics over specific time periods.

Request Body:
{
  "jsonrpc": "2.0",
  "method": "marketstack.calculateStockPerformance",
  "params": {
    "symbol": "AMZN",
    "time_period": "6months"  // Options: 1week, 1month, 3months, 6months, 1year, ytd
  },
  "id": "stock-3"
}
Response:
{
  "jsonrpc": "2.0",
  "result": {
    "performance": {
      "symbol": "AMZN",
      "time_period": "6months",
      "date_range": {
        "from": "2024-09-14",
        "to": "2025-03-14"
      },
      "start_price": 178.75,
      "end_price": 203.62,
      "price_change": 24.87,
      "percent_change": 13.91,
      "max_price": 208.23,
      "min_price": 165.93,
      "volatility": 12.38,
      "avg_daily_return": 0.1085,
      "annualized_return": 21.46,
      "annualized_volatility": 19.65,
      "sharpe_ratio": 1.09,
      "data_points": 128,
      "summary": "AMZN showed a positive trend over the 6months period, with a 13.91% change in price. The stock ranged from a low of 165.93 to a high of 208.23."
    }
  },
  "id": "stock-3"
}
Python Integration Example
import requests
import json

# Your API key
api_key = "your_api_key_here"

# API endpoint
url = "https://mcpfinancials.com/api/jsonrpc"

# Headers
headers = {
    "Content-Type": "application/json",
    "X-API-Key": api_key
}

# Example request for stock price data
payload = {
    "jsonrpc": "2.0",
    "method": "marketstack.getEodData",
    "params": {
        "symbols": "AAPL,MSFT,GOOGL",
    },
    "id": "market-request-1"
}

# Make the request
response = requests.post(url, headers=headers, json=payload)
data = response.json()

# Process the results
if "result" in data:
    stock_data = data["result"]["data"]
    for stock in stock_data:
        print(f"{stock['symbol']}: ${stock['close']} (Date: {stock['date']})")
else:
    print(f"Error: {data.get('error', 'Unknown error')}")

Time Series Analysis

Analyze and forecast time series data:

POST /api/v1/mcp

Forecast future values based on historical time series data.

Request Body:
{
  "type": "api",
  "action": "get",
  "parameters": {
    "integration": "financial",
    "query": "forecast_revenue",
    "data": {
      "revenue_series": [100, 120, 130, 140, 160, 170],
      "forecast_periods": 3
    }
  }
}
Response:
{
  "success": true,
  "data": {
    "forecast": [180, 190, 200],
    "model_params": {
      "slope": 14.0,
      "intercept": 92.0
    }
  }
}

Portfolio Optimization

Optimize asset allocation using modern portfolio theory:

POST /api/v1/mcp

Optimize portfolio weights for maximum returns at a given risk level.

Request Body:
{
  "type": "api",
  "action": "get",
  "parameters": {
    "integration": "financial",
    "query": "optimize_portfolio",
    "data": {
      "returns": {
        "AAPL": [0.01, 0.02, -0.01, 0.03, 0.01],
        "MSFT": [0.02, 0.01, 0.00, 0.02, 0.02],
        "GOOG": [0.03, -0.01, 0.02, 0.01, 0.01]
      },
      "risk_free_rate": 0.02
    }
  }
}
Response:
{
  "success": true,
  "data": {
    "weights": {
      "AAPL": 0.3,
      "MSFT": 0.4,
      "GOOG": 0.3
    },
    "expected_return": 0.042,
    "volatility": 0.12,
    "sharpe_ratio": 0.35
  }
}

Document API

The Document API allows you to upload, process, and search documents using OCR and vector embeddings.

Document Upload

Upload and process documents:

POST /documents/upload

Upload a document (PDF, image) for processing.

Form Data:
  • file (file, required): The document file to upload.
Response:
{
  "success": true,
  "document_id": "550e8400-e29b-41d4-a716-446655440000",
  "filename": "financial_report.pdf",
  "message": "Document uploaded successfully"
}

Semantic Search

Search document content using semantic similarity:

POST /documents/search

Search documents using semantic search.

Request Body:
{
  "query": "financial performance in Q3",
  "top_k": 5
}
Response:
{
  "success": true,
  "results": [
    {
      "document_id": "550e8400-e29b-41d4-a716-446655440000",
      "filename": "financial_report.pdf",
      "text_chunk": "In Q3 2024, the company reported strong financial performance with revenue growth of 15% year-over-year.",
      "score": 0.89,
      "metadata": {
        "page": 2
      }
    },
    // More results...
  ]
}

Storage API

The Storage API provides key-value storage capabilities for AI assistants to store and retrieve data.

POST /api/v1/mcp

Store a value in the storage system.

Request Body:
{
  "type": "storage",
  "action": "set",
  "parameters": {
    "key": "user_preferences",
    "value": {
      "theme": "dark",
      "currency": "USD"
    },
    "ttl": 86400
  }
}
Response:
{
  "success": true,
  "message": "Value stored successfully"
}
POST /api/v1/mcp

Retrieve a value from the storage system.

Request Body:
{
  "type": "storage",
  "action": "get",
  "parameters": {
    "key": "user_preferences"
  }
}
Response:
{
  "success": true,
  "data": {
    "theme": "dark",
    "currency": "USD"
  }
}

Webhooks

Webhooks allow you to receive notifications about events related to your account, such as subscription changes, API key usage, and more.

To set up a webhook endpoint, contact our support team.

Need Help?

If you have any questions or need assistance with our API, please contact our support team.