MCP · AI integration

Your assistant.
Headstart’s research.

Connect a compatible AI assistant to Headstart’s read-only research tools. Ask in plain English, then inspect the information behind the answer.

See connection steps ↓Manage AI connections →

↗Your AI assistant

You ask the question

MCPA read-only connection

Tools with defined permissions

HHeadstart research

Stored data, dates, and limitations

Production catalog

Start with definitions and proof counts.

The production tool catalog is limited to hs.explain_metric and hs.proof_summary, plus approved metadata resources and the market-research prompt.

Service availability still depends on deployment configuration. A credential does not unlock disabled tools.

Development / test catalog

19 tools. A broader research toolkit.

Includes market, company, options, earnings, portfolio, and watchlist research, with 13 resources/templates and 3 prompts.

Provider-backed production access remains restricted pending written redistribution approval.

From Account → AI Connections

Connect without handing over control.

Create a named credential.
Open Account → AI Connections. Give the connection a name you’ll recognize, such as “Research assistant.”
Choose permissions and expiry.
Use full read-only access or choose individual scopes. Available lifetimes are 30, 90, 180, or 365 days.
Save the one-time secret securely.
The hs_mcp_* secret is shown once. Store it in your client’s secret manager—not a public config, screenshot, or chat.
Configure and check your client.
Use the MCP endpoint supplied by your operator, or a trusted local checkout. Refresh tool discovery and start with “Explain Quant Score.”

Open AI Connections →

You choose the access

Read-only, scoped, revocable.

Market context · screens · ticker research
Options flow · events · track record
Model portfolios · portfolio analysis
Revoke an active credential from your account

Access also depends on your account entitlement and which capabilities are enabled. The connection cannot place trades, change your watchlist, or refresh data providers.

The current account UI labels this section “AI Connections.” This guide uses the same credential options.

Client configuration

Two supported connection paths.

These are configuration templates, not live credentials. Your MCP endpoint comes from your operator.

Remote · Streamable HTTP

{
  "mcpServers": {
    "headstart": {
      "type": "remote",
      "url": "<HEADSTART_MCP_URL>",
      "headers": {
        "Authorization": "Bearer <secret-store-reference>"
      }
    }
  }
}

Replace both bracketed values using your deployment details and client’s secret-storage mechanism. Client configuration syntax can vary.

Local checkout · stdio

{
  "mcpServers": {
    "headstart": {
      "command": "python3.11",
      "args": [
        "-m",
        "mcp_server",
        "--transport",
        "stdio"
      ],
      "env": {
        "MCP_ENABLED": "true",
        "HEADSTART_AGENT_API_URL": "http://127.0.0.1:8060",
        "HEADSTART_MCP_TOKEN": "<secret-store-reference>"
      }
    }
  }
}

Requires the installed Python 3.11 MCP service, its dependencies, a trusted checkout working directory, and a configured local backend. This page does not start a server.

Actual feature reference

Find the tool for your question.

Full development/test catalog. Production availability is narrower, as listed above.

Find a toolCatalog

19 tools in the development / test catalog

Market & discovery / 5 tools

hs.market_brief
Stored momentum cards, market exposure, macro, sector regime, and cached record-volume context
hs.market.read
hs.screen
Curated screen catalog and bounded screen members, including platform pick families
hs.screens.read
hs.ticker_search
Local ticker/company lookup
hs.ticker.read
hs.sector_regime
Market-wide sector breadth, leaders, laggards, and regime labels
hs.market.read
hs.record_volume
Cached scheduled record-volume breakthroughs
hs.market.read

Company research / 4 tools

hs.ticker_snapshot
Stored price, Quant Score, explanation evidence, and crowd sentiment
hs.ticker.read
hs.ticker_research
Ticker technicals, flow, ownership/events, earnings, setups, and persisted IV context
hs.ticker.read
hs.setup_flags
Stored-price NR7 and inside-day setup evidence for one ticker
hs.ticker.read
hs.iv_surface
Persisted ATM IV, IV rank, term slope, realized-volatility context, method, and source
hs.ticker.read

Options, events & earnings / 4 tools

hs.flow_intelligence
Alpha/whale options-flow evidence with contract details and limitations
hs.flow.read
hs.event_intelligence
Stored insider, Congress, and sentiment events
hs.events.read
hs.earnings_intelligence
Stored earnings dates, expected moves, IV-crush estimates, and historical context
hs.events.read
hs.dark_pool
Disclosed deep-ITM options-flow proxy; not confirmed dark-pool activity
hs.flow.read

Portfolios & watchlists / 3 tools

hs.model_portfolios
Stored hypothetical model-portfolio summaries and holdings
hs.portfolio.read
hs.portfolio_xray
Stateless analysis of user-supplied holdings
hs.portfolio.analyze
hs.watchlist
The authenticated user's watchlist, read-only
hs.portfolio.read

Track record & definitions / 3 tools

hs.proof_summary
Rights-approved aggregate proof counts
Public capability
hs.track_record
Stored outcome statistics and provenance split
hs.proof.read
hs.explain_metric
Product-owned metric definitions, units, and limitations
Public capability

hs.dark_pool is a deep-in-the-money options-flow approximation—not confirmed dark-pool activity. Watchlist access is read-only; portfolio X-ray analyzes the holdings you supply without saving changes.

Beyond individual tools

Resources to read. Prompts to start with.

13 resources and templates

Structured reference material and stored research. Availability follows the environment and permissions.

headstart://manifestheadstart://metricsheadstart://metrics/{key}headstart://screensheadstart://screens/{slug}headstart://screens/{slug}/historyheadstart://tickers/{symbol}/researchheadstart://flow/alpha-callsheadstart://eventsheadstart://track-record/{track}headstart://model-portfoliosheadstart://model-portfolios/{slug}headstart://model-portfolios/{slug}/backtest

3 research prompts

Try a real company: NVIDIA (NVDA). Its August 27, 2025 release reported $46.74B in quarterly revenue. Ask your assistant to compare the stored research with the company’s own report.

Company release ↗

hs.research.markeths.research.tickerhs.research.portfolio

Prompt examples for an enabled environment:

“Explain what Quant Score measures.”
“Summarize the stored market context and its dates.”
“Research NVIDIA (NVDA) and explain the dates and sources behind the answer.”

Use the company-research prompt only in an environment with the corresponding tools enabled. These are real tool use cases, not pre-generated AI answers. A prompt cannot bypass permissions.

Before your first question

A few practical answers.

Will this trade or update my account?

No. The MCP service is read-only. It does not execute strategies, place orders, mutate account data, or run provider refreshes.

Why can’t my assistant see all 19 tools?

The catalog is filtered by environment and enabled capabilities. Production currently permits only the two public tools described above. Permissions and account entitlement also apply to credentialed reads.

How should the assistant handle missing data?

Responses use the agent.v1 schema and explicit states: ok, partial, absent, computing, or error. Keep missing values and limitations visible; do not convert absence into zero or invent a result.

What if I lose or expose the secret?

Create a new credential and update your client. Revoke the old active credential in AI Connections. Never paste the secret into a public page or an AI conversation.

Can I use the same raw credential on data routes?

No. The raw AI credential is exchanged through the narrow introspection boundary for a short-lived delegated assertion. It is not forwarded directly to Agent-v1 data routes. Use the MCP client/service connection path.

Connect the assistant. Keep the judgment.

Manage the credential and permissions from your account.