> ## Documentation Index
> Fetch the complete documentation index at: https://docs.linqalpha.com/llms.txt
> Use this file to discover all available pages before exploring further.

# LinqAlpha MCP

> LinqAlpha MCP gives AI assistants direct access to institutional-grade financial data for fundamental research. Through the Model Context Protocol (MCP), your AI can query company fundamentals, earnings estimates, stock prices, economic indicators, SEC filings, and earnings transcripts — all from a single endpoint.

Supports JSON-RPC 2.0 protocol.

Available methods:
- `initialize` — Initialize MCP session
- `ping` — Health check
- `tools/list` — List available financial data tools
- `tools/call` — Execute a financial data tool

**Setup (Claude Desktop):**
```json
{
  "mcpServers": {
    "linqalpha": {
      "url": "https://api.linqalpha.com/v1/mcp",
      "headers": { "x-api-key": "<your-api-key>" }
    }
  }
}
```

## Overview

LinqAlpha MCP gives AI assistants direct access to institutional-grade financial data for fundamental research. Through the [Model Context Protocol](https://modelcontextprotocol.io), your AI (Claude, Cursor, etc.) can query company fundamentals, earnings estimates, stock prices, economic indicators, SEC filings, and earnings transcripts — all from a single endpoint.

## Quick Start

<Warning>
  If you already have an existing API key, you must request a new key with MCP permissions enabled. Existing keys issued before the MCP endpoint release do not have MCP access. Contact [support@linqalpha.com](mailto:support@linqalpha.com) to request a new key.
</Warning>

Add the following to your MCP client configuration:

<CodeGroup>
  ```json Claude Desktop theme={null}
  {
    "mcpServers": {
      "linqalpha": {
        "url": "https://api.linqalpha.com/v1/mcp",
        "headers": { "x-api-key": "<your-api-key>" }
      }
    }
  }
  ```

  ```bash Claude Code theme={null}
  claude mcp add linqalpha \
    --transport http \
    --url https://api.linqalpha.com/v1/mcp \
    --header "x-api-key: <your-api-key>"
  ```

  ```json Cursor theme={null}
  {
    "mcpServers": {
      "linqalpha": {
        "url": "https://api.linqalpha.com/v1/mcp",
        "headers": { "x-api-key": "<your-api-key>" }
      }
    }
  }
  ```
</CodeGroup>

## Use via Completion API

You can use LinqAlpha MCP tools directly from any LLM completion API (OpenAI, Anthropic, etc.) by making standard HTTP requests to our MCP endpoint. This lets you integrate LinqAlpha's financial data tools into your own AI workflows and applications.

### Step 1: List Available Tools

First, fetch the tool definitions to get their names and input schemas:

```python Python theme={null}
import requests

MCP_URL = "https://api.linqalpha.com/v1/mcp"
HEADERS = {
    "Content-Type": "application/json",
    "x-api-key": "<your-api-key>"
}

# List all available tools
response = requests.post(MCP_URL, headers=HEADERS, json={
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
})

tools = response.json()["result"]["tools"]
```

### Step 2: Convert to OpenAI Tool Format

Transform MCP tool definitions into the format expected by OpenAI's API:

```python Python theme={null}
def mcp_to_openai_tools(mcp_tools):
    """Convert MCP tool definitions to OpenAI function calling format."""
    openai_tools = []
    for tool in mcp_tools:
        openai_tools.append({
            "type": "function",
            "function": {
                "name": tool["name"],
                "description": tool["description"],
                "parameters": tool["inputSchema"]
            }
        })
    return openai_tools

openai_tools = mcp_to_openai_tools(tools)
```

### Step 3: Chat with Tool Calling

Use the converted tools in your OpenAI completion request, then execute any tool calls against LinqAlpha MCP:

```python Python theme={null}
from openai import OpenAI
import json

client = OpenAI()

messages = [
    {"role": "user", "content": "What was NVIDIA's revenue for the last 4 quarters?"}
]

# 1. Send request with tools
response = client.chat.completions.create(
    model="gpt-4o",
    messages=messages,
    tools=openai_tools,
)

message = response.choices[0].message

# 2. If the model calls a tool, execute it via LinqAlpha MCP
if message.tool_calls:
    messages.append(message)

    for tool_call in message.tool_calls:
        # Execute tool call against LinqAlpha MCP
        mcp_response = requests.post(MCP_URL, headers=HEADERS, json={
            "jsonrpc": "2.0",
            "id": 1,
            "method": "tools/call",
            "params": {
                "name": tool_call.function.name,
                "arguments": json.loads(tool_call.function.arguments)
            }
        })

        tool_result = mcp_response.json()["result"]["content"][0]["text"]

        messages.append({
            "role": "tool",
            "tool_call_id": tool_call.id,
            "content": tool_result
        })

    # 3. Get final response with tool results
    final_response = client.chat.completions.create(
        model="gpt-4o",
        messages=messages,
        tools=openai_tools,
    )

    print(final_response.choices[0].message.content)
```

<Tip>
  This pattern works with any LLM that supports function/tool calling — including Anthropic Claude API, Google Gemini, and open-source models. Just adapt the tool format conversion for your provider.
</Tip>

## Available Tools

LinqAlpha exposes **22 financial data tools** organized by category.

### Fundamentals & Estimates

| Tool                      | Description                                                                    |
| ------------------------- | ------------------------------------------------------------------------------ |
| `fundamentals_data_query` | Query financial datasets including fundamentals, estimates, and ownership data |
| `fundamentals_data_docs`  | Browse financial data schema documentation and available fields                |
| `stock_prices`            | Get historical and real-time stock price data                                  |
| `etf_reference`           | Get ETF metadata including expense ratios, strategies, and classifications     |
| `etf_metrics`             | List available ETF performance metrics                                         |

### Economic Data

| Tool                      | Description                                                                     |
| ------------------------- | ------------------------------------------------------------------------------- |
| `economic_data_query`     | Query macroeconomic data (GDP, CPI, employment, Treasury yields, VIX, and more) |
| `economic_indicators`     | List available economic indicators grouped by category                          |
| `economic_indicator_data` | Get economic indicator time series data (GDP, CPI, unemployment)                |
| `economic_calendar`       | Get upcoming economic data release schedule                                     |

### Market Data

| Tool                  | Description                                                                   |
| --------------------- | ----------------------------------------------------------------------------- |
| `forex_rates`         | Get foreign exchange currency pair rates and history                          |
| `commodity_prices`    | Get commodity market data (energy, metals, grains, softs)                     |
| `treasury_rates`      | Get US Treasury yield curve data across all maturities (1M-30Y)               |
| `market_symbols`      | List available market symbols for forex, commodities, and economic indicators |
| `market_risk_premium` | Get country-level market risk premium for CAPM calculations                   |

### Equity & Search

| Tool                    | Description                                                       |
| ----------------------- | ----------------------------------------------------------------- |
| `equity_database_query` | Query equity market database (stocks, events, documents)          |
| `transcript_search`     | Full-text search across earnings call transcripts and SEC filings |

### Research & Citations

| Tool                      | Description                                                                     |
| ------------------------- | ------------------------------------------------------------------------------- |
| `search_filings`          | Search and cite SEC filings, earnings transcripts, and financial news           |
| `cite_web_source`         | Create a web-based research citation                                            |
| `create_research_session` | Create a new research session for citation tracking                             |
| `get_citations`           | Retrieve all citations created in the current research session                  |
| `web_search`              | Search the web with date range filtering for recent financial news and analysis |

### Platform

| Tool               | Description                                            |
| ------------------ | ------------------------------------------------------ |
| `my_platform_data` | Query your organization's LinqAlpha platform data      |
| `list_guides`      | List available financial data guides and documentation |
| `read_guide`       | Read a specific financial data guide                   |

## Protocol

This endpoint implements [JSON-RPC 2.0](https://www.jsonrpc.org/specification) over HTTP, following the MCP specification.

### Supported Methods

| Method                      | Description                                            |
| --------------------------- | ------------------------------------------------------ |
| `initialize`                | Initialize MCP session and receive server capabilities |
| `ping`                      | Health check                                           |
| `notifications/initialized` | Client notification after initialization               |
| `tools/list`                | List all available tools with their input schemas      |
| `tools/call`                | Execute a tool with the given arguments                |

### Example: List Tools

```json Request theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}
```

```json Response theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "stock_prices",
        "description": "Get historical and real-time stock price data",
        "inputSchema": { ... }
      }
    ]
  }
}
```

### Example: Call a Tool

```json Request theme={null}
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "fundamentals_data_query",
    "arguments": {
      "sql": "SELECT ticker, revenue, net_income FROM financials WHERE ticker = 'AAPL' ORDER BY date DESC LIMIT 4"
    }
  }
}
```

```json Response theme={null}
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Query returned 4 rows..."
      }
    ]
  }
}
```

## Rate Limits

* **60 requests per minute** per user
* Exceeding the limit returns a JSON-RPC error with code `-32000`

## Error Codes

| Code     | Meaning                                  |
| -------- | ---------------------------------------- |
| `-32600` | Invalid JSON-RPC request                 |
| `-32601` | Method not found                         |
| `-32602` | Invalid params (e.g., unknown tool name) |
| `-32603` | Internal server error                    |
| `-32000` | Rate limit exceeded                      |


## OpenAPI

````yaml POST /v1/mcp
openapi: 3.0.1
info:
  title: LinqAlpha API
  description: >-
    Linq helps finance professionals make informed decisions using
    Retrieval-Augmented Generation (RAG)-enhanced answers. By leveraging
    cutting-edge Large Language Models (LLM) and supplementary technology, Linq
    provides the most optimized responses based on your queries.
  version: 1.0.0
  license:
    name: MIT
servers:
  - url: https://api.linqalpha.com
security:
  - ApiKeyAuth: []
tags:
  - name: Search
    description: Search and generate responses
  - name: Data
    description: Data retrieval and mapping
  - name: Feedback
    description: Conversation feedback
  - name: RMS
    description: Research Management System
  - name: Source Management
    description: Source batch and file management
  - name: MCP
    description: >-
      LinqAlpha MCP — Financial data tools for AI assistants via Model Context
      Protocol
  - name: Connectors
    description: Customer Connectors — customer-owned MCP connector management
  - name: Briefing
    description: Briefing Agent — automated market briefings with scheduling and delivery
  - name: Status
    description: Sync status — check organization, document, and container sync progress
paths:
  /v1/mcp:
    post:
      tags:
        - MCP
      summary: LinqAlpha MCP
      description: >-
        LinqAlpha MCP gives AI assistants direct access to institutional-grade
        financial data for fundamental research. Through the Model Context
        Protocol (MCP), your AI can query company fundamentals, earnings
        estimates, stock prices, economic indicators, SEC filings, and earnings
        transcripts — all from a single endpoint.


        Supports JSON-RPC 2.0 protocol.


        Available methods:

        - `initialize` — Initialize MCP session

        - `ping` — Health check

        - `tools/list` — List available financial data tools

        - `tools/call` — Execute a financial data tool


        **Setup (Claude Desktop):**

        ```json

        {
          "mcpServers": {
            "linqalpha": {
              "url": "https://api.linqalpha.com/v1/mcp",
              "headers": { "x-api-key": "<your-api-key>" }
            }
          }
        }

        ```
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/McpJsonRpcRequest'
      responses:
        '200':
          description: JSON-RPC 2.0 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpJsonRpcResponse'
        '400':
          description: Invalid JSON-RPC request
        '401':
          description: Authentication failed
components:
  schemas:
    McpJsonRpcRequest:
      type: object
      required:
        - jsonrpc
        - method
      properties:
        jsonrpc:
          type: string
          enum:
            - '2.0'
          description: JSON-RPC version
        method:
          type: string
          enum:
            - initialize
            - ping
            - notifications/initialized
            - tools/list
            - tools/call
          description: MCP method to invoke
        id:
          type: integer
          description: Request identifier
        params:
          type: object
          description: >-
            Method-specific parameters. For tools/call: { name: string,
            arguments: object }
    McpJsonRpcResponse:
      type: object
      properties:
        jsonrpc:
          type: string
          enum:
            - '2.0'
        id:
          type: integer
          nullable: true
          description: Request identifier (null for error responses)
        result:
          type: object
          description: Method result (present on success)
        error:
          type: object
          properties:
            code:
              type: integer
              description: JSON-RPC error code
            message:
              type: string
              description: Error message
          description: Error object (present on failure)
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY

````