# Understanding MCP Tools > Learn how to connect Corbis to Cursor, Claude Code, ChatGPT, and other MCP clients using API keys or supported OAuth flows. The **Model Context Protocol (MCP)** lets other AI clients call tools from Corbis. That means you can use Corbis research and data tools inside products like **Cursor**, **Claude Code**, **ChatGPT**, and other MCP-compatible clients instead of staying only inside the Corbis web app. --- ## Why People Use MCP MCP is useful when you want to: - run Corbis tools from your editor or another AI interface - keep your research flow in one place - bring source-backed paper search and economic data into another client - avoid copying results back and forth by hand --- ## Client setup ### Claude Add a custom connector named Corbis, use the universal URL, and choose OAuth. ```text https://www.corbis.ai/api/mcp/universal ``` [Open Claude connector settings](https://claude.ai/customize/connectors?modal=add-custom-connector) ### ChatGPT Create an app connector named Corbis, use the universal URL, and complete OAuth. Corbis issues refresh tokens, so the connection renews on its own and does not need a daily reconnect. ```text https://www.corbis.ai/api/mcp/universal ``` [Open ChatGPT connector settings](https://chatgpt.com/plugins) ### Cursor Add the JSON server entry below, then approve the browser sign-in Cursor opens — Cursor detects the Corbis OAuth server automatically. No API key is needed: Cursor may ignore static Authorization headers when OAuth discovery is available, so OAuth is the supported Cursor path. ```json { "mcpServers": { "corbis": { "url": "https://www.corbis.ai/api/mcp/universal" } } } ``` ### Claude Code Run the command below after setting CORBIS_MCP_API_KEY in the shell that launches Claude Code. ```bash claude mcp add --transport http corbis https://www.corbis.ai/api/mcp/universal --header "Authorization: Bearer ${CORBIS_MCP_API_KEY}" ``` ## MCP Tool Catalog This catalog is generated from Corbis's canonical MCP registry. Access depends on your account and key configuration. - `search_papers`: Search Papers (research). Hybrid academic paper search. - `get_paper_details`: Get Paper Details (research). Fetch full metadata for a single paper. - `get_paper_details_batch`: Get Paper Details Batch (research). Fetch full metadata for multiple papers in one call. - `literature_search`: Literature Search (research). Managed staged literature review and synthesis pipeline. - `research_opportunity_map`: Research Opportunity Map (research). Embedding-based candidate gap, bridge, and conflict mapper for research ideation. - `literature_retrieve`: Literature Retrieve (research). Retrieve paper candidates for local external-agent synthesis. - `paper_discovery`: Paper Discovery (research). Multi-facet paper discovery and deduped triage over the paper layer. - `literature_positioning`: Literature Positioning (research). Position a thesis against nearby paper-layer literature with verification-needed signals. - `evidence_pack`: Evidence Pack (research). Build paper-level evidence packs for claim-specific review. - `claim_verification`: Claim Verification (research). Premium paper-layer claim verification precheck with fail-closed sparse retrieval. - `fred_search`: FRED Search (economic). Search FRED economic series metadata. - `fred_series_batch`: FRED Series Batch (economic). Fetch multiple FRED series in one call. - `get_market_data`: Get Market Data (market). Get a CRE market snapshot. - `get_metric_definitions`: Get Metric Definitions (market). Return schema and definitions for CRE market metrics. - `compare_markets`: Compare Markets (market). Compare multiple CRE markets side by side. - `search_markets`: Search Markets (market). Rank or search markets by metric. - `screen_markets`: Screen Markets (market). Multi-factor CRE market screening. - `get_national_macro`: Get National Macro (market). Fetch national macroeconomic indicators. - `get_market_trends`: Get Market Trends (market). Fetch metro-level historical trend series. - `get_cre_market`: Get CRE Market (market). CRE market snapshot by property type with national benchmarks. - `search_cre_markets`: Search CRE Markets (market). Rank metros by a CRE metric within a property type. - `get_cre_trend`: Get CRE Trend (market). Annual CRE transaction trend for a metro. - `search_cre_listings`: Search CRE Listings (market). Live for-sale / for-lease CRE inventory. - `get_cre_comps`: Get CRE Comps (market). Individual securitized (CMBS) property comps. - `get_cre_operating`: Get CRE Operating Fundamentals (market). Same-store rent/NOI growth + occupancy by metro × sector (REIT supplementals). - `get_reit_transaction_caps`: Get REIT Transaction Caps (market). National by-sector REIT acquisition/disposition cap rates. - `get_cbre_cap_rate_survey`: Get CBRE Cap Rate Survey (market). CBRE Cap Rate Survey history and segment/class drill-downs (survey expectation, not closed deals). - `internet_search`: Web Search (web). Managed web search with Corbis-side summary. - `read_web_page`: Read Web Page (web). Extract a web page for analysis. - `web_search_retrieve`: Web Search Retrieve (web). Retrieve web result cards for local external-agent synthesis. - `web_pages_retrieve`: Web Pages Retrieve (web). Retrieve bounded page extracts for local external-agent synthesis. - `deep_research`: Deep Research (web). Run a managed multi-engine web research synthesis pass. - `export_citations`: Export Citations (citation). Format supplied citation metadata into export files for MCP clients. - `render_citations`: Render Citations (citation). Render corpus-verified citations from OpenAlex IDs, DOI IDs, chat citation sets, document snapshots, or run IDs. - `top_cited_articles`: Top Cited Articles (research). Rank highly cited papers within journals. - `format_citation`: Format Citation (citation). Format citations in multiple styles. - `search_datasets`: Search Datasets (research). Discover relevant external datasets. - `find_academic_identity`: Find Research Identity (identity). Search for the user research profile candidate. - `confirm_academic_identity`: Confirm Research Identity (identity). Link or unlink public research profile anchors. - `get_research_pulse`: Get Research Pulse (identity). Return the authenticated user research pulse for ResearchBar and MCP clients. - `get_data_freshness`: Get Data Freshness (market). Aggregate data-through and last-refreshed signals for Corbis data sources. - `retrieve_document`: Retrieve Document (document). Retrieve an existing artifact document. - `query_corbis`: Query Corbis (workflow). Delegate a managed tool-grounded sub-query to Corbis. - `query_corbis_retrieve`: Query Corbis Retrieve (workflow). Retrieve compact Corbis evidence packets for local external-agent synthesis. - `referee_report_evaluate`: Evaluate Referee Report (workflow). Evaluate local external-agent referee report inputs and return a calibrated deliverable. - `technical_audit_evaluate`: Evaluate Technical Audit (workflow). Evaluate local external-agent technical audit findings and return a calibrated deliverable. - `verify_bibtex`: Verify BibTeX (citation). Audit BibTeX reference lists for correctness and completeness. --- ## The Easiest Setup For most users, the simplest setup is a **personal MCP API key** from Corbis. ### Step 1: Create a key In Corbis, open **Settings → API Keys**, create an **MCP** key, and copy it when it is shown. Important: - copy the token when it is shown - tokens are only revealed once - revoke and replace a key if you think it has been exposed ### Step 2: Point your client at the universal endpoint Use **your Corbis origin** (the same host you use in the browser for the app—not a marketing URL unless that is where the app actually runs). The MCP path you need is: **`/api/mcp/universal`** Build the full URL as: **the same origin you use for the web app** (scheme, host, and port if any) **plus** the path `/api/mcp/universal`. Most clients connect with that URL plus your MCP key. ### Step 3: Use the connection method your client expects Corbis already helps with the common cases: - **Cursor:** one-click install or downloadable JSON config - **Claude Code:** copyable setup command - **Other MCP clients:** universal endpoint plus your key If you are not sure which transport to use, prefer the **streamable HTTP** setup against `/api/mcp/universal` unless your client docs require something else. --- ## Authentication (API key vs OAuth) - **Personal MCP API keys** — Created in **Settings → API Keys**. This is the default path for clients that let you set a custom header (Claude Code, Codex, and similar): send the key as an `Authorization: Bearer …` header. - **OAuth** — Used when the client signs you in and approves access in the web app. **Cursor**, and hosted assistant connectors such as ChatGPT and Claude, use this path: they take the MCP URL alone and run the sign-in flow themselves, so their config carries no key. OAuth access tokens use the same `Authorization: Bearer …` header style after you complete the client's login flow. **Security:** Credentials in the URL query string (`?apikey=` / `?token=`) are **rejected in production** — they leak through logs, referrers, and shared links. They work only against a local development server. Always use a **Bearer header or OAuth**. OAuth scope and consent details for implementers are documented in **`lib/mcp/OAUTH2_IMPLEMENTATION.md`** in the repository (not required reading for basic API-key setup). --- ## Advanced / other surfaces Prefer **`/api/mcp/universal`** for new setups. Other routes exist for compatibility and discovery: - **`/api/mcp/sse`** and **`/api/mcp/message`** — Legacy SSE transport pair for clients that need a dedicated SSE URL instead of streamable HTTP on the universal route. - **`/.well-known/oauth-protected-resource`**, **`/.well-known/oauth-authorization-server`**, **`/.well-known/openid-configuration`** — OAuth / OpenID discovery metadata for clients that probe well-known URLs. - **`/api/mcp/oauth/register`**, **`/api/mcp/oauth/authorize`**, **`/api/mcp/oauth/token`** — Dynamic registration, authorization, and token exchange for supported OAuth integrations. This section names routes only; it is not a full OAuth tutorial. --- ## Practical Tips - Create separate keys for separate devices or clients. - Name keys clearly so you can revoke the right one later. - Treat MCP keys like passwords. - If a tool seems missing, check your plan and the key configuration first. - If a client offers both modern HTTP MCP and older SSE-based options, prefer HTTP on `/api/mcp/universal` unless you know you need the legacy path. --- ## Common Questions ### Do I need a paid plan to use MCP? No. Most Corbis MCP tools work on every plan, including free: paper search, citation tools, FRED economic data, and the CRE market-data tools among them. A small set of advanced tools (such as deep research, web search and page reading, literature search, claim verification, the referee and technical-audit evaluators, and managed Corbis queries) is enterprise-only. Your exact tool list also depends on your key configuration, so the authoritative answer is the `tools/list` response on your own connection (the tool list your client shows is that response). The `docs://tool-access` MCP resource explains the tier, scope, and key-allowlist rules behind it, and your current plan and limits are in Corbis settings. ### Can I use Corbis from my editor? Yes. That is one of the main MCP use cases. ### Can I connect more than one client? Yes. Many users create separate keys for different clients so they can revoke them independently. ### Where do I get help if the connection fails? Start in **Settings → API Keys** and make sure you are using the right endpoint and token. If that still fails, contact [Corbis support](/contact). --- ## Further reading (repository) If you are working from a checkout of the Corbis codebase: - **`docs/ai-sdk/mcp/`** — Corbis MCP guides (Cursor plugin, Claude Code, Codex, and related). - **`lib/mcp/CHATGPT_GUIDE.md`** — ChatGPT-oriented setup notes. --- ## Related Guides - [Quick Start Guide](/docs/quick-start) - [Plans & Pricing](/docs/plans-and-pricing)