\n\n# Magellan Data MCP\n\n**Corporate ownership intelligence for AI agents.** Connect Claude, Cursor, or any\nMCP-compatible client to [Magellan Data](https://magellandata.io)'s Spotlight platform\nand ask who owns whom — parent companies, PE backing, corporate families, and portfolio\nsiblings — over lists of thousands of companies at a time.\n\nHosted server. No install. Connect with an API key, or via OAuth from hosted\nconnectors like claude.ai.\n\n```\nhttps://spotlight-mcp.magellandata.io/mcp\n```\n\nThat's an MCP endpoint, not a web page — paste it into your client's config, not your\nbrowser. Opening it directly returns an error, which is the correct behaviour for every\nhosted MCP server.\n\n---\n\n## Try asking\n\nOnce connected, these all work in plain language:\n\n> \"Read `accounts.xlsx` and tell me which of these companies are PE-backed, and by whom.\"\n\n> \"We just closed Moosend. Find every other company owned by the same PE firm — those are\n> our warm expansion targets.\"\n\n> \"Which of my 200 accounts are subsidiaries of a larger parent? Append the parent company\n> to the spreadsheet and save it.\"\n\n> \"Map the full corporate family under Constant Contact's parent so I can see the sister\n> companies I'm not covering.\"\n\nThe agent handles the whole pipeline — submitting the batch, polling until the runs\nfinish, checking the price, and joining results back to your original file by `input_url`.\n\n---\n\n## Quick start\n\n**1. Get an API key.** Sign up at [magellandata.io](https://magellandata.io) and generate a\nkey from the Spotlight dashboard. Keys look like `mgln_sk_live_…`. Every key carries its own\ncredit balance, and usage is billed to the key that made the call.\n\n**2. Connect your client.**\n\n\nClaude Code\n\n```bash\nclaude mcp add --transport http magellan-data https://spotlight-mcp.magellandata.io/mcp \\\n --header \"Authorization: Bearer mgln_sk_live_YOUR_KEY\"\n\nclaude mcp list # expect: magellan-data ... ✓ Connected\n```\n\n\n\nCursor\n\nAdd to `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project):\n\n```json\n{\n \"mcpServers\": {\n \"magellan-data\": {\n \"url\": \"https://spotlight-mcp.magellandata.io/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer mgln_sk_live_YOUR_KEY\"\n }\n }\n }\n}\n```\n\n\n\nVS Code\n\nAdd to `.vscode/mcp.json` — this prompts for the key rather than storing it in the file:\n\n```json\n{\n \"inputs\": [\n {\n \"type\": \"promptString\",\n \"id\": \"magellanKey\",\n \"description\": \"Magellan Data API key (mgln_sk_live_...)\",\n \"password\": true\n }\n ],\n \"servers\": {\n \"magellan-data\": {\n \"type\": \"http\",\n \"url\": \"https://spotlight-mcp.magellandata.io/mcp\",\n \"headers\": { \"Authorization\": \"Bearer ${input:magellanKey}\" }\n }\n }\n}\n```\n\n\n\nAny other MCP client\n\nThe server speaks **Streamable HTTP** and is stateless. Point any compliant client at\n`https://spotlight-mcp.magellandata.io/mcp` with an `Authorization: Bearer ` header.\n\n\n**3. Verify.** Ask your agent: *\"Check my Magellan Data credit balance.\"* If it comes back\nwith a number, you're connected. That call is free.\n\n---\n\n## Authentication\n\nTwo methods are supported; use whichever fits how you're connecting.\n\n**API keys** (`mgln_sk_live_…`) — for local and CLI clients like Claude Code, Cursor, or\nanything you configure by hand. Generate a key in the\n[Spotlight dashboard](https://magellandata.io) and pass it as a Bearer token in the\n`Authorization` header, as shown in the quick start above. Usage is billed to the key\nthat made the call.\n\n**OAuth 2.1** — for hosted connectors such as claude.ai and ChatGPT. There's nothing\nOAuth-specific to set up on your side: when you add the connector (from the directory,\nor as a custom connector where the platform holds the client credentials), you'll be\nsent to Spotlight to sign in and approve access — the usual \"connect, sign in, allow\"\nflow — and the client handles tokens from there. Usage is billed to the Spotlight\naccount you approved with.\n\nEither way, every request is authenticated and attributed to one Spotlight account —\nthe two methods differ only in how the credential reaches the server.\n\n---\n\n## What you can look up\n\n| Output type | Answers | Cost |\n| --- | --- | --- |\n| `parent_companies` | Is this company a subsidiary, and of whom? | 70 credits per URL **where a parent is found** — no match, no charge |\n| `pe_ownership` | Is it PE-backed, by which firm, and what deal type? | 70 credits per URL **found to be PE-backed** — no match, no charge |\n| `corporate_families` | Every subsidiary and sister company under a shared parent | 20 credits per record returned (min. 1 per URL) |\n| `pe_portfolios` | Every company held by the same PE firm | 20 credits per record returned (min. 1 per URL) |\n\nFor `parent_companies` and `pe_ownership` you pay only for hits: a URL where nothing is\ndiscovered costs nothing, so 70 credits × your URL count is the *ceiling*, not the bill.\nThe other two are priced per output record. Either way the exact price is known once a\nrun completes — the agent reads it off the run and tells you before downloading.\n\n---\n\n## How credits work\n\nThis is the part worth understanding, because it's what keeps an autonomous agent from\nquietly burning your balance:\n\n- **Submitting a batch is free.** So is starting the processing runs, polling their status,\n and checking your balance.\n- **Credits are charged at exactly one point:** `download_run`. Nothing before it costs\n anything.\n- **The agent surfaces the price first.** Every run carries a `price` field, and the server\n instructs connected clients to state that number and wait for you before downloading.\n- **Re-downloads are free, forever.** Once a run is purchased it stays purchased. If a\n download link expires, just ask again — no second charge.\n\nIf you'd rather not think about it: everything up to and including \"how much will this\ncost\" is free, and the agent will ask.\n\n---\n\n## Tools\n\n| Tool | Charges credits? | What it does |\n| --- | --- | --- |\n| `check_credits` | No | Your available balance. Doubles as a connection check. |\n| `submit_batch` | No | Create a batch from 1–5,000 company URLs. Returns a `batch_id`. |\n| `process_batch` | No | Start async runs — one per output type. Returns immediately. |\n| `list_runs` | No | Every run for a batch: status, price, purchase state. |\n| `get_run_status` | No | One run's status and price. Poll this until `completed`. |\n| `download_run` | **Yes** | Buys the results. Returns a short download link plus a preview. |\n\nThe flow is always **submit → process → poll → download**. Results come back as a short\ndownload link (`https://api.magellandata.io/dl/…`, valid for 1 hour) rather than inline,\nso a 2-million-row result set never touches your agent's context window. The link needs\nno auth header — hand it straight to `curl`, `pandas.read_csv`, or a browser. In hosted\nchat environments without general internet access (like the claude.ai connector), the\nassistant presents it as a clickable link for you to open rather than fetching it itself.\n\nThere's also a **`magellan_playbook` prompt** — a GTM strategy guide covering expansion-\ntarget ranking, `deal_type` interpretation, and MSA-timing triggers. In Claude Code it shows\nup as a slash command under the `magellan-data` server.\n\n---\n\n## Working example\n\n[`examples/quickstart.py`](examples/quickstart.py) runs the full pipeline against the REST\nAPI directly — useful for understanding what the agent is doing under the hood, or for\nwiring Magellan Data into a non-agentic pipeline.\n\n```bash\nexport MAGELLAN_API_KEY=mgln_sk_live_YOUR_KEY\npython examples/quickstart.py --urls moosend.com constantcontact.com --type pe_ownership\n```\n\n[`examples/accounts.csv`](examples/accounts.csv) and\n[`accounts.xlsx`](examples/accounts.xlsx) are a 12-row fixture you can point an\nagent at without supplying your own data. The companies span independents, acquired\nsubsidiaries, and PE-backed businesses, so each output type returns something. Enriching all\ntwelve costs at most 840 credits per match-based output type (only the companies where\nsomething is found are charged) — cheap enough to validate the pipeline for real.\n\nIt stops and asks before the download step, so you can run it end to end without spending\ncredits until you mean to.\n\n[`examples/PROMPTS.md`](examples/PROMPTS.md) has a walkthrough of agent prompts in\nincreasing order of ambition, with the expected cost of each noted up front.\n\n---\n\n## Skills\n\nThe [`skills/`](skills/) directory holds task-focused playbooks that turn raw tool output\ninto a finished deliverable — a ranked target list, a coverage map, an enriched\nspreadsheet — instead of JSON. Clients that support skills can load them from this repo;\nclients that don't can still be pointed at the markdown directly.\n\n| Skill | Produces |\n| --- | --- |\n| `account-expansion` | Ranked warm-intro targets from a closed-won account's ownership graph |\n| `pe-portfolio-map` | Coverage map of a PE firm's portfolio against your existing accounts |\n| `ownership-enrichment` | Your account list, enriched in place with parent and PE-backing columns |\n\n---\n\n## Repository contents\n\n```\n.mcp.json MCP registration (Claude Code, Codex)\nmcp.json MCP registration (Cursor)\n.vscode/mcp.json MCP registration (VS Code, prompts for key)\n.claude-plugin/\n plugin.json Claude plugin metadata\n marketplace.json Claude marketplace metadata\nserver.json Official MCP Registry metadata\nskills/*/SKILL.md Task playbooks\nexamples/\n quickstart.py Full pipeline against the REST API\n PROMPTS.md Agent prompt walkthrough\n accounts.csv 12-row test fixture\n accounts.xlsx Same fixture, spreadsheet form\nassets/\n logo.png Wordmark, navy (for light backgrounds)\n logo-light.png Wordmark, white (for dark backgrounds)\n social-preview.png 1280x640 social card — upload under\n Settings > Social preview\n social-preview-light.png Light-background alternate\n```\n\nTo use the manifests locally:\n\n```bash\ngit clone https://github.com/sorrek/mcp.git\n```\n\nThen point your client at the repo root or the specific manifest path.\n\n---\n\n## Troubleshooting\n\n**The endpoint URL shows an error in my browser.**\nExpected. `/mcp` speaks JSON-RPC over POST; the transport spec reserves GET on that path for\nopening an event stream, so a server like this one that doesn't offer streams answers with\n405. There's nothing to see there. To check the server is actually up, ask your agent to\ncall `check_credits` — that's free and exercises the whole auth path.\n\n**My client connects but lists no tools.**\nAlmost always an auth problem rather than a transport one. Confirm the header is\n`Authorization: Bearer mgln_sk_live_...` with the `Bearer ` prefix, and that the key is\nactive in the Spotlight dashboard.\n\n**A download link says it has expired (HTTP 410).**\nDownload links last an hour. Call `download_run` again for a fresh one — re-downloads are\nfree.\n\n**A run has been `processing` for a long time.**\nLarge batches take minutes, not seconds. Poll every 10–30 seconds rather than in a tight\nloop. If a run sits past 20 minutes, open an issue with the `run_id`.\n\n---\n\n## Notes and limits\n\n- **Batch size:** up to 5,000 URLs per batch. Larger lists should be chunked; the agent will\n do this if you ask.\n- **Timing:** large runs take minutes, not seconds. Polling every 10–30 seconds is the right\n cadence and the server instructions say so.\n- **Overlapping inputs:** if two input companies share a parent or a PE firm, you're charged\n for both inputs. Every output row carries `input_url`, so deduplicating client-side is\n trivial.\n- **Auth:** every request carries either an API key or an OAuth token (see\n [Authentication](#authentication)), so usage is always attributed to the right\n Spotlight account.\n\n---\n\n## Roadmap\n\n- Listing in the official MCP Registry and downstream directories\n- `last_verified` timestamps on ownership records\n\nIssues and feature requests are welcome — open one on this repo.\n\n---\n\n## Support\n\n- **API documentation:** [docs.magellandata.io](https://docs.magellandata.io)\n- **Bugs and requests:** [open an issue](https://github.com/sorrek/mcp/issues)\n- **Data quality problems:** [support@magellandata.io](mailto:support@magellandata.io?subject=Data%20quality%20issue)\n- **Commercial questions:** [magellandata.io](https://magellandata.io)\n\n## License\n\n[MIT](LICENSE) — this repository. The Spotlight API itself is a commercial service governed\nby the Magellan Data terms of service.\n",
"bytes": 13055,
"sha": "c3c111efde2475ee3d940d61f6c0d7d3973e098a7a2151c58ca2955cf8c27d73",
"repo_slug": "sorrek/mcp",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_magellandata_spotlight_2bcccd89/readme"
}
![\"Magellan](\"assets/logo-light.png\"){kind=logo}
\n