Authentication - YFinance MCP Server

Overview

The Financial MCP Server uses a hybrid authentication model depending on the data source and deployment method. Understanding the authentication requirements is crucial for proper setup and usage.

YFinance tools require no authentication, while FMP tools require an API key for full functionality.

Authentication Methods

1. No Authentication (YFinance)

YFinance tools work immediately without any setup:

# Works without any API keys
curl "http://localhost:8001/api/v1/stock/AAPL/yfinance"

Available without authentication:

Basic stock quotes
Company information
Historical data
Symbol search
Analyst recommendations
Insider transactions

2. FMP API Key (Professional Tools)

FMP tools require a valid API key for access:

# Requires FMP_API_KEY environment variable
curl "http://localhost:8001/api/v1/stock/AAPL"

Getting FMP API Key

Step 1: Create Account

Visit Financial Modeling Prep
Click “Sign Up” to create a free account
Verify your email address
Complete the registration process

Step 2: Access Dashboard

Log in to your FMP account
Navigate to the API Dashboard
Find your API key in the “API Key” section
Copy the key for use in your application

Step 3: Choose Plan

Plan	Requests/Day	Price	Features
Free	250	$0	Basic data, perfect for development
Starter	1,000	$15/month	Production-ready for small apps
Professional	10,000	$50/month	High-volume applications
Enterprise	Custom	Custom	Unlimited with premium support

Environment Configuration

Local Development

# Set environment variables
export FMP_API_KEY="your_actual_api_key_here"
export PORT=8001

# Start the server
python3 main.py

# Create .env file in project root
echo "FMP_API_KEY=your_actual_api_key_here" > .env
echo "PORT=8001" >> .env

# Load and start
source .env
python3 main.py

# Windows Command Prompt
set FMP_API_KEY=your_actual_api_key_here
set PORT=8001
python main.py

# Windows PowerShell
$env:FMP_API_KEY="your_actual_api_key_here"
$env:PORT=8001
python main.py

Production Deployment

# Set environment variables in Railway dashboard
FMP_API_KEY=your_actual_api_key_here
PORT=$PORT

# Set config vars
heroku config:set FMP_API_KEY=your_actual_api_key_here
heroku config:set PORT=8001

version: '3.8'
services:
  financial-mcp:
    build: .
    environment:
      - FMP_API_KEY=your_actual_api_key_here
      - PORT=8001
    ports:
      - "8001:8001"

# Add to systemd service file
Environment=FMP_API_KEY=your_actual_api_key_here
Environment=PORT=8001

API Key Validation

Testing Your Setup

# Test FMP API key
curl "http://localhost:8001/api/v1/stock/AAPL"

# Expected: Stock data with "source": "FMP"

# Test YFinance (no API key needed)
curl "http://localhost:8001/api/v1/stock/AAPL/yfinance"

# Expected: Stock data from Yahoo Finance

# Check server status
curl "http://localhost:8001/api/v1/health"

# Expected: Server health and tool availability

Server Response Indicators

Valid FMP API Key

{
  "symbol": "AAPL",
  "price": 201.08,
  "source": "FMP",
  "timestamp": "2025-06-28T18:42:12.471731"
}

Invalid/Missing FMP API Key

{
  "error": "FMP API key required. Set FMP_API_KEY environment variable.",
  "setup_instructions": "Get a free API key at: https://financialmodelingprep.com/developer/docs"
}

YFinance Fallback Active

{
  "symbol": "AAPL",
  "price": 201.08,
  "currency": "USD",
  "timestamp": "2025-06-28T18:42:12.471731"
}

Rate Limiting & Quotas

FMP Rate Limits

Rate limits are enforced per API key:

Plan	Daily Limit	Per-Minute Limit	Overage
Free	250	5	Blocked
Starter	1,000	20	$0.01/request
Professional	10,000	100	$0.005/request

Rate Limit Headers

FMP responses include rate limit information:

X-RateLimit-Limit: 250
X-RateLimit-Remaining: 247
X-RateLimit-Reset: 1640995200
X-RateLimit-Used: 3

Handling Rate Limits

The server automatically handles rate limiting:

# Automatic rate limit detection
if "rate limit" in response.get("error", "").lower():
    # Fallback to YFinance if available
    # Or return rate limit error with retry information

Security Best Practices

1. API Key Protection

Environment Variables

✅ DO: Store API keys in environment variables

export FMP_API_KEY="your_key"

❌ DON’T: Hardcode keys in source code

# NEVER DO THIS
FMP_API_KEY = "your_actual_key_here"

Version Control

✅ DO: Add .env to .gitignore

echo ".env" >> .gitignore

❌ DON’T: Commit API keys to repositories

Production Deployment

✅ DO: Use platform environment variable systems

Railway: Environment Variables tab
Heroku: Config Vars
Docker: Environment variables

❌ DON’T: Include keys in Docker images or config files

2. Access Control

# Optional: Add API key validation for your endpoints
@app.middleware("http")
async def validate_access(request: Request, call_next):
    # Add your own authentication logic here
    response = await call_next(request)
    return response

3. Monitoring & Alerting

# Monitor API usage
@app.middleware("http")
async def log_requests(request: Request, call_next):
    start_time = time.time()
    response = await call_next(request)
    process_time = time.time() - start_time
    
    logger.info("Request processed", extra={
        "path": request.url.path,
        "method": request.method,
        "process_time": process_time,
        "status_code": response.status_code
    })
    
    return response

Troubleshooting

Common Issues

Invalid API Key

Symptoms: 401 Unauthorized errorsSolutions:

Verify API key is correct (copy-paste from FMP dashboard)
Check environment variable is set: echo $FMP_API_KEY
Restart server after setting environment variables
Ensure no extra spaces or characters in the key

Rate Limit Exceeded

Symptoms: 429 Too Many Requests errorsSolutions:

Check your FMP dashboard for usage statistics
Implement caching to reduce API calls
Upgrade to higher tier plan
Use YFinance endpoints for basic data

Environment Variables Not Loading

Symptoms: Server uses “demo” key despite setting FMP_API_KEYSolutions:

Restart terminal/shell after setting variables
Use printenv | grep FMP to verify variables are set
Check .env file is in correct directory
Ensure proper syntax in environment files

Debugging Commands

# Verify environment variables
echo "FMP API Key: $FMP_API_KEY"
echo "Port: $PORT"

# Check if variables are exported
printenv | grep FMP

# Direct API test
curl "https://financialmodelingprep.com/api/v3/quote/AAPL?apikey=$FMP_API_KEY"

# Should return AAPL data if key is valid

# Check server logs for authentication issues
python3 main.py 2>&1 | grep -i "api\|auth\|key"

Migration Guide

From Demo to Production

Get Production API Key

# Replace demo key with production key
export FMP_API_KEY="your_production_key"

Update Deployment Configuration

# Update your deployment platform
# Railway: Environment Variables
# Heroku: heroku config:set FMP_API_KEY=new_key

Test Production Setup

# Verify production key works
curl "http://your-domain.com/api/v1/stock/AAPL"

Monitor Usage
- Check FMP dashboard regularly
- Set up usage alerts
- Plan for scaling if needed

​Overview

​Authentication Methods

​1. No Authentication (YFinance)

​2. FMP API Key (Professional Tools)

​Getting FMP API Key

​Step 1: Create Account

​Step 2: Access Dashboard

​Step 3: Choose Plan

​Environment Configuration

​Local Development

​Production Deployment

​API Key Validation

​Testing Your Setup

​Server Response Indicators

​Valid FMP API Key

​Invalid/Missing FMP API Key

​YFinance Fallback Active

​Rate Limiting & Quotas

​FMP Rate Limits

​Rate Limit Headers

​Handling Rate Limits

​Security Best Practices

​1. API Key Protection

​2. Access Control

​3. Monitoring & Alerting

​Troubleshooting

​Common Issues

​Debugging Commands

​Migration Guide

​From Demo to Production

​Next Steps

Get FMP API Key

Installation Guide

API Reference

Deployment Guide

Overview

Authentication Methods

1. No Authentication (YFinance)

2. FMP API Key (Professional Tools)

Getting FMP API Key

Step 1: Create Account

Step 2: Access Dashboard

Step 3: Choose Plan

Environment Configuration

Local Development

Production Deployment

API Key Validation

Testing Your Setup

Server Response Indicators

Valid FMP API Key

Invalid/Missing FMP API Key

YFinance Fallback Active

Rate Limiting & Quotas

FMP Rate Limits

Rate Limit Headers

Handling Rate Limits

Security Best Practices

1. API Key Protection

2. Access Control

3. Monitoring & Alerting

Troubleshooting

Common Issues

Debugging Commands

Migration Guide

From Demo to Production

Next Steps