etfedge-mcp

ETFedge owner-only read-only MCP service. Every HTTP request requires the single bearer stored in MCP_OWNER_TOKEN; this is not a public integration.

Codex owner setup

Keep the same long random token in server secret storage and the MCP_OWNER_TOKEN environment variable, then add this to ~/.codex/config.toml:

[mcp_servers.etfedge]
url = "https://mcp.etfedge.xyz/mcp"
bearer_token_env_var = "MCP_OWNER_TOKEN"

There is no OAuth login or public account onboarding. A missing or mismatched bearer receives 401 before FastMCP handles the request.

Related MCP server: options-chain-mcp

Local run

pip install -e .
cp .env.example .env
set -a; . ./.env; set +a
python mcp_server.py

MCP_DATABASE_URL should use the existing read-only PostgreSQL role. Never put the bearer or database URL in this repository.

The owner retains the existing safe generic tools: allowlisted relation queries, freshness, ETF holdings and deltas, stock history, the legacy market-value view, the estimated unrealized-P&L helper, and cross-ETF consensus buys. Arbitrary SQL is not exposed. This is an owner-only private research interface; it is not a public data API.

Private fund research contract

The safe generic tools may list, describe, query, and report freshness for the allowlisted fund_metrics table and the derived fund_metrics_resolved and fund_flow_daily PostgreSQL views. These relations must always be queried with at least an etf_code or as_of_date filter, and every generic query is capped at 500 rows. No arbitrary relation, SQL, write, raw bytes, or secret-bearing column is exposed.

fund_metrics.as_of_date is the portfolio date after the pipeline's calibrated date shift. created_at and updated_at are ingest metadata, not a source publication time. fund_flow_daily.units_delta and creation_ntd are derived proxies from changes in units outstanding and NAV, not confirmed issuer cash flows. prev_as_of_date identifies the previous resolved observation used for that proxy. When interpreting a flow, retain its source and source_adapter.

For example, a bounded owner query can request one ETF's recent observations:

{
  "table": "fund_flow_daily",
  "filters": [
    {"column": "etf_code", "op": "eq", "value": "00981A"},
    {"column": "as_of_date", "op": "gte", "value": "2026-08-01"}
  ],
  "sort_by": "as_of_date",
  "sort_dir": "desc",
  "limit": 30
}