API Reference
Model Context Protocol
The Alphalyst MCP exposes earnings intelligence data as structured tools consumable by LLM agents, Claude, and any MCP-compatible client.
1. What is MCP
The Model Context Protocol (MCP) is an open standard for exposing structured data and actions to AI agents. Alphalyst implements an MCP server that surfaces earnings events, political trade disclosures, and transcript summaries as typed tools callable by any compliant client.
Each tool accepts typed parameters and returns a JSON object. Responses are designed to be embedded directly into LLM context without further parsing.
2. Getting started
- Step 1 — Create an API key. Go to Settings → API keys and click New key. Keys are prefixed sk-ep-. Copy it immediately — it will not be shown again.
- Step 2 — Choose a plan. Standard keys allow 30 requests/min and 1,000 requests/hr. Pro keys allow 120 requests/min and 10,000 requests/hr. Limits are enforced per API key.
- Step 3 — Authenticate. Pass the key as the Authorization header:
Authorization: Bearer sk-ep-<your-key> - Step 4 — Call a tool. All MCP tools are available at POST /mcp/v1/call with a JSON-RPC 2.0 body.
3. Tool reference
All tools use JSON-RPC 2.0. Parameters marked * are required.
get_upcoming_earnings
Returns scheduled earnings events for a ticker within a lookahead window.
| Param | Type | Description |
|---|---|---|
| ticker* | string | Equity ticker symbol (e.g. AAPL). |
| window_days | integer | Lookahead window in days. Default: 14. |
Returns: Array of { event_id, ticker, company_name, scheduled_at, fiscal_quarter }.
get_earnings_summary
Returns the LLM-generated summary for the most recent completed earnings call.
| Param | Type | Description |
|---|---|---|
| ticker* | string | Equity ticker symbol. |
| event_id | string | Specific event ID. Defaults to latest. |
Returns: { event_id, ticker, summary_text, eps_beat, guidance_tone, generated_at }.
get_political_trades
Returns disclosed political trades for a ticker from House/Senate filings.
| Param | Type | Description |
|---|---|---|
| ticker* | string | Equity ticker symbol. |
| days_back | integer | Lookback window in days. Default: 90. |
| chamber | string | Filter by chamber: house | senate | all. Default: all. |
Returns: Array of { filing_id, legislator, transaction_type, amount_range, disclosed_at }.
get_news_summary
Returns the AI-generated news digest for a ticker over a recent window.
| Param | Type | Description |
|---|---|---|
| ticker* | string | Equity ticker symbol. |
| window_days | integer | Window in days. Default: 7. |
Returns: { ticker, headline_summary, sentiment, article_count, generated_at }.
get_ticker_timeline
Returns the full event timeline for a ticker across all event types.
| Param | Type | Description |
|---|---|---|
| ticker* | string | Equity ticker symbol. |
| limit | integer | Max events to return. Default: 50, max: 200. |
| event_types | string[] | Filter by type: earnings | news | political_trade | filing. |
Returns: { events: Event[], total }.
get_watchlist_events
Returns upcoming events for all tickers in the authenticated user's watchlist.
| Param | Type | Description |
|---|---|---|
| window_days | integer | Lookahead window in days. Default: 14. |
| event_types | string[] | Filter by event type. |
Returns: Array of { ticker, company_name, event_type, scheduled_at }.
4. Rate limits
| Plan | Per minute | Per hour |
|---|---|---|
| Standard | 30 | 1,000 |
| Pro | 120 | 10,000 |
Rate limit headers are returned on every response: X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (Unix timestamp). When exceeded, the API returns HTTP 429 with JSON-RPC error code -32029.
5. Error reference
All errors follow JSON-RPC 2.0 format: { "error": { "code": -32xxx, "message": "..." } }
| Code | HTTP | Meaning |
|---|---|---|
| -32700 | 400 | Parse error — malformed JSON body. |
| -32600 | 400 | Invalid request — missing jsonrpc/method field. |
| -32601 | 404 | Method not found — unknown tool name. |
| -32602 | 422 | Invalid params — required param missing or wrong type. |
| -32603 | 500 | Internal error — unexpected server failure. |
| -32001 | 401 | Unauthorized — missing or invalid API key. |
| -32003 | 403 | Forbidden — key does not have access to this tool. |
| -32029 | 429 | Rate limit exceeded — slow down requests. |
6. Python SDK
The official Python SDK wraps the JSON-RPC transport and provides typed return objects.
Install
pip install earnings-pulse-mcpQuick start
import earnings_pulse_mcp as ep
client = ep.Client(api_key="sk-ep-...")
# List upcoming earnings events
events = client.tools.get_upcoming_earnings(ticker="AAPL", window_days=14)
print(events)More examples
import earnings_pulse_mcp as ep
client = ep.Client(api_key="sk-ep-...")
# Latest earnings summary
summary = client.tools.get_earnings_summary(ticker="MSFT")
# Political trade disclosures
trades = client.tools.get_political_trades(ticker="AAPL", days_back=90)Set the EARNINGS_PULSE_API_KEY environment variable to avoid passing the key explicitly. The client reads it automatically.
7. Troubleshooting
I get -32001 (Unauthorized) but my key looks correct.
Ensure the key is passed as a Bearer token in the Authorization header, not as a query parameter. Keys are case-sensitive. If the key was recently created, wait 10 seconds for propagation.
Responses are stale — data looks days old.
Check the generated_at or computed_at field in the response. If it is older than expected, the ingest worker may be behind. Contact support with the event_id.
I hit rate limits even at low request volume.
Limits apply per API key, not per IP. If multiple processes share a key, aggregate their usage. Upgrade to Pro or use separate keys per service.
Political trade disclosed_at dates look wrong.
The platform uses filed_at from the disclosure filing when transaction_date is absent. This is expected for some older filings. The disclosed_at field is authoritative for compliance purposes.
8. Changelog
- Initial MCP server launch with 8 tools.
- Standard and Pro rate limit tiers.
- Python SDK earnings-pulse-mcp published to PyPI.
- JSON-RPC 2.0 transport with typed error codes.
- Political trade disclosures from House and Senate filings.
Research only · No execution · Verify all figures · Not financial advice