Quick Start

Choose your deployment option:

🚀 Option 1: Use Our Hosted Instance (Fastest)

No installation required!

1. Get FMP API Key: Sign up at FMP
2. Connect to our endpoint: https://financial-modeling-prep-mcp-server-production.up.railway.app/mcp
3. Provide API key in session configuration
4. Start using 5 meta-tools to load toolsets dynamically

Available via:

• Direct HTTP connection (recommended)
• MCP registries like Smithery.ai, Glama.ai, Contexaai.com

Example session config:

{
  "FMP_ACCESS_TOKEN": "your_fmp_api_key_here"
}

🏠 Option 2: Self-Host Your Own Instance (Full Control)

Choose your mode and deploy:

NPM Installation:

npm install -g financial-modeling-prep-mcp-server
export FMP_ACCESS_TOKEN=your_token_here
export DYNAMIC_TOOL_DISCOVERY=true  # or choose static/legacy
fmp-mcp

Docker (build from source):

git clone https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server
cd Financial-Modeling-Prep-MCP-Server
docker build -t fmp-mcp-server .
docker run -p 8080:8080 \
  -e FMP_ACCESS_TOKEN=your_token_here \
  -e DYNAMIC_TOOL_DISCOVERY=true \
  fmp-mcp-server

See Installation Methods for detailed self-hosting options.

Features

• Powered by Toolception: Built on toolception for robust server orchestration and dynamic tool management
• 5 Meta-Tools in Dynamic Mode: enable_toolset, disable_toolset, list_toolsets, describe_toolset, list_tools
• Comprehensive Coverage: Access to 253+ financial tools across 24 categories
• Flexible Deployment: Use our hosted instance or self-host with full control
• Tool Set Filtering: Load only the tools you need to reduce complexity and improve performance
• Dynamic Tool Loading: Runtime enable/disable of tool categories via meta-tools
• Real-time Data: Live stock quotes, market data, and financial information
• Financial Statements: Income statements, balance sheets, cash flow statements, and financial ratios
• Market Analysis: Technical indicators, analyst estimates, and market performance metrics
• Economic Data: Treasury rates, economic indicators, and macroeconomic information
• Alternative Data: ESG scores, insider trading, congressional trading, and social sentiment

Deployment Options

This server can be used in two ways:

📡 Using Our Hosted Instance (Recommended for Quick Start)

Direct HTTP Endpoint:

https://financial-modeling-prep-mcp-server-production.up.railway.app/mcp

Also available through MCP registries:

• Smithery.ai: View on Smithery
• Glama.ai, Contexaai.com (see Registries section)

Configuration:

• Runs in dynamic mode (5 meta-tools: enable_toolset, disable_toolset, list_toolsets, describe_toolset, list_tools)
• Requires FMP API key in session configuration (not server environment)
• No server-side setup needed - just connect and use

🏠 Self-Hosting Your Own Instance (Full Control)

Deploy your own instance for complete control:

• Choose any mode: Dynamic, Static, or Legacy
• Configure via: Environment variables or CLI arguments
• Deployment options: NPM, Docker, or from source
• See Installation Methods below

Server Architecture

This MCP server leverages toolception - a dynamic MCP server toolkit for runtime toolset management with Fastify transport and meta-tools. Toolception provides complete server orchestration including HTTP transport, session management, and tool lifecycle.

Key Features:

• Powered by Toolception: Uses toolception for server orchestration and dynamic tool management
• Client-level Caching: Toolception's ClientResourceCache maintains isolated sessions per client with LRU/TTL eviction
• Session Isolation: Each client gets their own MCP server instance with independent tool state
• Stateful Management: Sessions maintain their state across multiple requests via toolception's session management
• Mode Enforcement: Server-level configurations can override session-level settings
• HTTP-based Protocol: Communicates via HTTP with JSON-RPC formatted messages using Fastify transport
• Dynamic Tool Management: Tools can be loaded/unloaded at runtime per session using toolception's DynamicToolManager

Transport & Client Compatibility

Important: This server uses HTTP/SSE transport only (no stdio). See compatibility notes below.

| Client | Support | How to Connect | |--------|---------|----------------| | Claude.ai | Yes | Settings > Connectors > Add remote server | | Claude Desktop | Yes | Settings > Connectors (NOT claude add or config.json) | | Claude Mobile | Yes | Uses servers added via claude.ai | | Smithery/Glama | Yes | Via registry with server card | | Custom HTTP | Yes | Include mcp-client-id header |

Claude Desktop users: Do NOT use claude add <url> or edit claude_desktop_config.json - these expect stdio transport. Instead, add as a remote server via Settings > Connectors.

See Anthropic's Remote MCP Server Guide.

Request Flow:

1. Client Request → HTTP POST to / endpoint
2. Session Management → Toolception creates or retrieves session based on client ID (caching via ClientResourceCache)
3. Mode Resolution → Server determines operational mode (Dynamic/Static/Legacy)
4. Tool Registration → Toolception's ModuleResolver lazy-loads tools based on resolved mode
5. Request Processing → MCP request is processed with available tools via toolception's orchestrator
6. Response → JSON-RPC response sent back to client

Available HTTP Endpoints:

• POST /mcp - Main MCP protocol endpoint (JSON-RPC formatted messages)
  • Requires session initialization - see Session Management
• GET /ping - Simple ping endpoint (returns {"status": "ok"})
• GET /healthcheck - Comprehensive health check endpoint
• GET /.well-known/mcp/server-card.json - MCP server card for auto-discovery (SEP-1649)

Configuration & Mode Enforcement

The server supports multiple configuration methods with a clear precedence hierarchy to ensure predictable behavior.

Understanding Server Modes

The server supports three operational modes. The mode you use depends on your deployment scenario:

Using Our Hosted Instance (Railway)

• Fixed Mode: Dynamic mode (5 meta-tools)
• Configuration: Pass FMP_ACCESS_TOKEN in session config
• Use Case: Quick start without