MCP Protocol

The Model Context Protocol (MCP) enables AI assistants like Claude to interact with Paper's API using natural language. Trade, manage portfolios, and analyze market data through conversational interfaces.

Getting Started

Prerequisites

Before setting up MCP integration, you'll need:

Paper Trading Account - Sign up at app.paperinvest.io
API Key - Generate from your account settings

Installation

For Claude Desktop

Install Claude Desktop from claude.ai
Configure MCP in your Claude settings:

Claude Desktop Configuration

JSON

claude_desktop_config.json

{
  "mcpServers": {
    "paper-invest": {
      "command": "npx",
      "args": ["@paperinvest/mcp-server"],
      "env": {
        "PAPER_INVEST_API_KEY": "your-api-key-here"
      }
    }
  }
}

Restart Claude Desktop to load the MCP server

For Other AI Assistants

Paper's MCP server can be integrated with any AI assistant that supports the Model Context Protocol. Contact your AI provider for specific integration instructions.

Available Tools

The MCP server provides comprehensive tools for account management, trading, portfolio operations, and market data access.

Account Management Tools

Tool	Description	Example
`get_account`	Get account details by ID	Show me account details for account-123
`update_account`	Update account name	Rename my account to "Long Term Holdings"
`freeze_account`	Freeze a trading account	Freeze my trading account

Portfolio Management Tools

Tool	Description	Example
`create_portfolio`	Create a new portfolio within an account	Create an IRA portfolio in my account
`get_portfolio`	Get portfolio details	Show me my main portfolio
`get_account_portfolios`	List all portfolios for an account	Show all my portfolios
`reset_portfolio`	Reset portfolio to initial state	Reset my test portfolio

Trading Tools

Tool	Description	Example
`create_order`	Place a new order (supports all order types)	Buy 100 shares of AAPL at market price
`create_batch_orders`	Create multiple orders at once	Buy AAPL, MSFT, and GOOGL in one batch
`get_order`	Get specific order details	Show me order 123e4567-e89b-12d3
`cancel_order`	Cancel an existing order	Cancel order 123e4567-e89b-12d3
`get_account_orders`	List orders for an account	Show me all my pending orders
`cancel_all_account_orders`	Cancel all orders for an account	Cancel all my open orders
`get_today_filled_orders`	Get all orders filled today	Show me all trades executed today

Supported Order Types

The create_order tool supports all order types:

MARKET - Execute immediately at best available price
LIMIT - Execute at specified price or better
STOP - Convert to market order when stop price is reached
STOP_LIMIT - Convert to limit order when stop price is reached
TRAILING_STOP - Stop price follows favorable price movements
TRAILING_STOP_LIMIT - Trailing stop that converts to limit order
DEBIT - Multi-leg option strategy with net debit
CREDIT - Multi-leg option strategy with net credit
EVEN - Multi-leg option strategy with no net debit/credit
BRACKET - Parent order with automatic take-profit and stop-loss

Position Tools

Tool	Description	Example
`get_portfolio_equities`	Get all equity positions in a portfolio	Show me all stocks in my portfolio
`get_portfolio_options`	Get all option positions in a portfolio	Show me my option positions

Market Data Tools

Tool	Description	Example
`get_quote`	Get real-time price quote for a symbol	What is the current price of MSFT?
`get_batch_quotes`	Get quotes for multiple symbols at once	Show me prices for AAPL, MSFT, and GOOGL
`get_market_hours`	Get market hours for an exchange	What are the market hours today?
`is_market_open`	Check if market is open for a symbol	Is the market open for trading AAPL?

Activity & Reporting Tools

Tool	Description	Example
`get_portfolio_activities`	Get activity log for a portfolio	Show me all activities in my portfolio today
`get_day_trades`	Get day trade activity for a portfolio	Show me my day trades this week

Margin Trading Tools

Tool	Description	Example
`upgrade_to_margin`	Upgrade portfolio to margin account	Upgrade my portfolio to margin trading

Example Conversations

Basic Trading

Example: Market Order

Conversation

User: Buy 50 shares of Apple


Claude: I'll help you buy 50 shares of Apple (AAPL). Let me first check the current price.


[Checking current price of AAPL...]
Current price: $175.25


I'll place a market order for 50 shares of AAPL.


[Placing order...]
✓ Order placed successfully!
- Order ID: 123e4567-e89b-12d3-a456-426614174000
- Symbol: AAPL
- Quantity: 50 shares
- Order Type: Market
- Estimated Cost: $8,762.50 (plus fees)

Portfolio Analysis

Example: Portfolio Review

Conversation

User: Show me how my portfolio is performing today


Claude: I'll analyze your portfolio performance for today.


[Retrieving portfolio data...]


Your Portfolio Performance Today:
- Total Value: $125,430.50
- Today's Change: +$1,245.75 (+1.00%)


Holdings:
1. AAPL: 100 shares @ $175.25 (+2.1% today)
2. MSFT: 50 shares @ $425.50 (-0.5% today)
3. GOOGL: 25 shares @ $145.75 (+1.8% today)


Cash Balance: $45,230.25
Buying Power: $90,460.50

Advanced Orders

Example: Limit Order

Conversation

User: Set a limit order to buy Tesla if it drops to $240


Claude: I'll create a limit order to buy Tesla (TSLA) at $240 or better.


[Checking current TSLA price...]
Current price: $245.50


[Creating limit order...]
✓ Limit order created!
- Order ID: 456e7890-e89b-12d3-a456-426614174111
- Symbol: TSLA
- Type: Limit Buy
- Limit Price: $240.00
- Time in Force: Day


Your order will execute if TSLA reaches $240 or lower today.

Security

API Key Management

Never share your API key in conversations or screenshots
Use environment variables to store sensitive credentials
Rotate keys regularly from your account settings
Set key permissions to limit access to specific operations

Best Practices

Start with small trades to familiarize yourself with the system
Verify order details before confirming large trades
Monitor your positions regularly
Use limit orders for better price control
Review activity logs to track all operations

Configuration Options

Environment Variables

Variable	Description	Required
`PAPER_INVEST_API_KEY`	Your Paper Trading API key	Yes
`PAPER_BASE_URL`	API base URL (default: https://api.paperinvest.io)	No

Limitations

Paper trading only - All trades are simulated, not real
Market hours - Some operations may be limited outside trading hours
Rate limits - Subject to API rate limiting (see Rate Limiting)
Supported securities - Currently supports US equities only

Troubleshooting

Common Issues

Issue	Solution
MCP server not connecting	Check API key and restart Claude Desktop
Orders failing	Verify portfolio has sufficient buying power
Market data unavailable	Check if market is open and symbol is valid
Authentication errors	Regenerate API key and update configuration

MCP Protocol

Getting Started

Prerequisites

Installation

For Claude Desktop

Claude Desktop Configuration

For Other AI Assistants

Available Tools

Account Management Tools

Portfolio Management Tools

Trading Tools

Supported Order Types

Position Tools

Market Data Tools

Activity & Reporting Tools

Margin Trading Tools

Example Conversations

Basic Trading

Example: Market Order

Portfolio Analysis

Example: Portfolio Review

Advanced Orders

Example: Limit Order

Security

API Key Management

Best Practices

Configuration Options

Environment Variables

Limitations

Troubleshooting

Common Issues

See Also