--- name: marked-setup description: Connect an AI agent to Marked via MCP or the REST API and run a first live query against Indian market data. --- # Connect to Marked Help the user connect to Marked and get one live query working against Indian market data. Marked is a financial data layer for AI agents covering Indian capital markets: company financials, filings and disclosures, ownership and shareholding, corporate actions, insider activity, market prices and corporate events. Coverage is 9,400+ listed Indian companies, 1.3M+ financial facts and 29K+ filings, served as structured JSON with the source filing attached to every value. There is no CLI for end users. Every surface exposes the same data, packaged differently. **MCP server** (recommended for interactive clients — Claude, Cursor, Codex, ChatGPT, and anything else that speaks MCP): - Server: `https://app.marked.run/mcp/` - Transport: streamable HTTP - Auth: an API key sent as a header. Marked does not use OAuth. **REST API** (scripts, notebooks, backends that are not MCP clients): - Base URL: `https://app.marked.run` - Auth: `X-API-Key` header, or `Authorization: Bearer ` How to think about it: - Using Claude, Cursor, Codex or ChatGPT? Go MCP. - Writing a script or calling from your own backend? Go REST. - Either way you need a key first, and **a key cannot be self-issued** — see below. ## Getting a key **Marked has no self-serve signup.** There is no endpoint an agent can call to open an account, and no checkout link to mint. Keys are issued per workspace by the Marked team. Ask for one at **access@marked.run**, or from the site at https://marked.run. Do not attempt to create an account programmatically; no such endpoint exists. A key looks like `mk_live_...`. It is shown once, at issue, and only its hash is stored, so it cannot be recovered afterwards — if it is lost, it has to be reissued. Keys belong to a workspace, and the workspace carries the plan and the monthly request allowance: | Plan | Requests / month | |------|-----------------:| | Developer | 2,000 | | Builder | 25,000 | | Scale | 500,000 | | Enterprise | uncapped | API requests and MCP tool calls draw on the **same** monthly pool. Every response carries `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` so an agent can pace itself. Over the limit, requests answer `429` and are not billed. ## MCP setup by client ### Claude Code ```bash claude mcp add --transport http marked https://app.marked.run/mcp/ \ --header "X-API-Key: YOUR_API_KEY" ``` Verify with `claude mcp list`. ### Claude (claude.ai and Claude Desktop) 1. Settings → Connectors → Add custom connector 2. URL: `https://app.marked.run/mcp/` 3. Add an `X-API-Key` header with your key 4. In a new chat, click + and enable Marked under Connectors ### ChatGPT Settings → Plugins → MCPs → Add: - **Name:** `marked` - **Type:** `Streamable HTTP` - **URL:** `https://app.marked.run/mcp/` - **Headers:** key `X-API-Key`, value your key Leave "Bearer token env var" empty; the header is enough. ### Cursor Add to `~/.cursor/mcp.json`, save, and restart Cursor: ```json { "mcpServers": { "marked": { "url": "https://app.marked.run/mcp/", "headers": { "X-API-Key": "YOUR_API_KEY" } } } } ``` ### Codex ```bash codex mcp add marked --url https://app.marked.run/mcp/ \ --header "X-API-Key: YOUR_API_KEY" ``` Verify with `codex mcp list`, or type `/mcp` in Codex. Most MCP clients load servers only at startup. After adding the server, restart the client or open a new chat before the tools appear. Tell the user if that is needed and wait for them before continuing. ## Tools Nineteen tools are exposed over MCP: `search`, `get_company`, `get_quote`, `get_historical_prices`, `get_financials`, `get_financial_history`, `screen_companies`, `list_screen_metrics`, `get_shareholding`, `get_corporate_actions`, `get_events`, `list_event_types`, `get_insider_activity`, `search_filings`, `get_filing`, `get_earnings`, `query`, `get_fact_provenance`, `list_datasets`. Use `query` for a research question in plain language, and the typed tools when you already know what you want. `get_fact_provenance` returns every observation ever published for one number, with the filing each came from. ## First query Once connected, run one real query end to end so the user sees it work. Suggested first calls: - Latest quote for RELIANCE - Last four quarters of consolidated financials for RELIANCE - Who holds TCS, and at what percentage? Ask it as a question and let the agent pick its tools. A well-connected client should reach for `search` or `get_company` first to resolve the name. ## REST API Company names resolve however a person writes them — `reliance`, `RELIANCE`, `Reliance Industries Ltd` and the ticker all reach the same company. Latest quote: ```bash curl "https://app.marked.run/v1/prices?ticker=RELIANCE" \ -H "X-API-Key: YOUR_API_KEY" ``` Financials: ```bash curl "https://app.marked.run/v1/financials?ticker=RELIANCE&limit=4" \ -H "X-API-Key: YOUR_API_KEY" ``` The agent-facing surface is flat and self-describing. `GET /v1/` lists every endpoint and the row count behind each dataset: ``` GET /v1/ what exists, and how much of it GET /v1/companies company master GET /v1/financials income statement, balance sheet, cash flow GET /v1/financial-metrics derived ratios and growth rates GET /v1/filings filings and disclosures GET /v1/shareholding ownership and shareholding patterns GET /v1/corporate-actions dividends, splits, bonuses, buybacks GET /v1/events corporate events GET /v1/prices quotes GET /v1/instruments tradable instruments POST /v1/search search across the corpus POST /v1/query structured query POST /v1/ask a research question in plain language ``` ## Provenance Every financial value carries the filing it came from. When two sources report the same company, concept, period and basis differently, Marked returns one canonical answer chosen by source quality — structured XBRL over a PDF scrape, exchange over investor relations, most recent as the final tiebreak — never by whichever row was written first. Values that cannot be attributed to a period are withheld from answers rather than guessed at. If an answer matters, ask for its provenance. `get_fact_provenance` (MCP) and `GET /api/v1/companies/{reference}/financials/{concept_id}/provenance` (REST) return the full restatement trail. ## If something breaks - **Tools missing after adding the server** — restart the client or open a new chat, then retry. - **`401`** — the key is missing, wrong or revoked. Confirm the `X-API-Key` header is set. Every tool call answers 401 before it runs, so no tools appear at all. - **`404` on a key you believe exists** — keys are scoped to a workspace, and one workspace cannot see another's. The answer is the same whether the key is absent or belongs to someone else. - **`429`** — the workspace has spent its monthly requests. Check `RateLimit-Reset` for when the period rolls over, or move up a plan. - **`307` on the MCP URL** — the trailing slash is missing. Use `https://app.marked.run/mcp/`, not `/mcp`. Some clients drop the request body across a redirect. Support: **access@marked.run**