HeronIntelligence-mcp 0.20.0

HeronIntelligence Financial Intelligence — MCP server for AI assistants

Heron Intelligence MCP

Heron Intelligence — financial research MCP server for AI assistants.

Connect Heron Intelligence's research capabilities (curated earnings call transcripts, due diligence interviews, and conversational research project intake) directly to Claude, Cursor, or any MCP-compatible client.

The remote server is available at https://mcp.heron-intelligence.com/mcp and authenticates via OAuth 2.1 (Streamable HTTP transport). A stdio mode using a static API key is also supported for local desktop integrations.

Requirements

• An active Heron Intelligence account
• For local stdio mode: an API key + uvx
• For Claude.ai / Claude Desktop remote mode: just the OAuth flow

Installation

Claude.ai (remote, OAuth)

In Claude.ai, add a custom connector pointing to:

https://mcp.heron-intelligence.com/mcp

You'll be redirected to Heron Intelligence to authorize the connection, then returned to Claude.

Claude Desktop (local stdio)

Add to ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "heron": {
      "command": "uvx",
      "args": ["--from", "HeronIntelligence-mcp", "heronintelligence-mcp"],
      "env": {
        "HERON_API_KEY": "hk-xxxx"
      }
    }
  }
}

Restart Claude Desktop.

Claude Code

claude mcp add heron \
  --command uvx \
  --args "--from HeronIntelligence-mcp heronintelligence-mcp" \
  -e HERON_API_KEY=hk-xxxx \
  -s user

Cursor / Windsurf

Add to your MCP config:

{
  "mcpServers": {
    "heron": {
      "command": "uvx",
      "args": ["--from", "HeronIntelligence-mcp", "heronintelligence-mcp"],
      "env": {
        "HERON_API_KEY": "hk-xxxx"
      }
    }
  }
}

Tool reference

All tools include MCP ToolAnnotations so MCP-compliant clients can apply appropriate auto-approval policies.

Tool	Title	Type
whoami	Get authenticated user	read-only
search_company	Search companies	read-only
get_company_overview	Get company coverage overview	read-only
get_recent_transcripts	List recent transcripts	read-only
get_transcript_content	Get transcript content	read-only
get_project_status	Get research project status	read-only
start_research_project	Start research project	write (non-destructive)
define_research_brief	Define research brief (Step 1)	write (non-destructive)
prepopulate_research_configuration	Prepopulate research configuration	write (non-destructive)
configure_research_project	Configure research project (Step 2)	write (non-destructive)
generate_research_questions	Generate research questions (Step 3)	write (non-destructive)
submit_research_project	Submit research project (Step 4)	write (non-destructive)

Read-only tools may auto-approve in supporting clients; write tools always require explicit user confirmation.

Example queries

Once connected, ask your AI assistant:

"What is Nubank's management saying about churn this year?"

"Compare guidance changes between MercadoLibre's last 4 quarters."

"Start a due diligence research project on the LATAM neobanking sector."

Billing tiers

Tier	Monthly	API Calls	RPM	Data Window
Trial	Free (14d)	100	5	Last 2 quarters
Starter	$199	500	10	Last 4 quarters
Professional	$499	2,000	30	Last 8 quarters
Enterprise	Custom	Unlimited	100	Full history

Quota errors

When your quota is exhausted the tool returns a human-readable message:

Heron Intelligence quota limit reached: Monthly request quota exhausted.
Your quota resets at 2026-04-01T00:00:00+00:00.

The API also sets response headers you can inspect:

Header	Meaning
X-RateLimit-Limit-Minute	Requests allowed per minute
X-Quota-Requests-Remaining	Requests left this month
X-Quota-Reset	ISO timestamp when the monthly counter resets
Retry-After	Seconds to wait (RPM 429 only)

Environment variables

See .env.example for the full template. Secrets must be supplied at runtime through your deployment's environment — never committed in plaintext.

Required (HTTP mode)

Variable	Description
HERON_BASE_URL	Backend API URL (e.g. https://api.heron-intelligence.com)
MCP_SERVICE_KEY	Service-to-service key for the Heron Intelligence backend
OAUTH_JWT_SECRET	HS256 signing secret for OAuth access tokens

Required (stdio mode only)

Variable	Description
HERON_API_KEY	Per-user Heron Intelligence API key (from your dashboard)

Public configuration (non-secret)

Variable	Default	Description
MCP_CANONICAL_URI	https://mcp.heron-intelligence.com	OAuth audience / protected-resource id
OAUTH_JWT_ISSUER	matches canonical URI	JWT issuer claim
MCP_ALLOWED_ORIGINS	claude.ai surfaces + canonical URI	Comma-separated Origin allowlist
HERON_TIMEOUT	120.0	HTTP request timeout for backend calls (seconds)
OAUTH_ACCESS_TOKEN_TTL	3600	Access-token lifetime (seconds)
MCP_TRANSPORT	stdio	Set to http to run as a remote MCP via uvicorn
PORT	8080	Listening port for HTTP mode

Documentation

• API documentation: https://docs.heron-intelligence.com
• MCP setup guide: https://docs.heron-intelligence.com/mcp

Privacy policy

Heron Intelligence's privacy policy is available at https://www.heron-intelligence.com/privacy-policy.

The MCP server transmits user queries and OAuth identity to the Heron Intelligence backend over TLS. The server does not collect, store, or share data beyond what is required to fulfill the tool call. Authentication tokens are stored encrypted at rest. See the linked policy for full details on data collection, retention, third-party sharing, and GDPR rights.

Support

• Email: [e-mail]
• Issues: https://github.com/auraresearch/aura-core-mcp/issues

License

Proprietary — requires an active Heron Intelligence subscription.