> For the complete documentation index, see [llms.txt](https://docs.orbitfin.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.orbitfin.ai/orbit-api-reference/mcp/2.1-orbit-mcp-setup.md).

# 2.1 Orbit MCP Setup

### 1. Overview <a href="#heading-17e4230e-4444-4c7c-bcc1-f83210b378ef--1-overview-0" id="heading-17e4230e-4444-4c7c-bcc1-f83210b378ef--1-overview-0"></a>

Orbit exposes two access channels, both of which require authentication:

* **MCP (Model Context Protocol) Server** — for AI agents and LLM clients such as Claude, ChatGPT, and Cursor.

To support both machine-to-machine integrations and end-user delegated access, Orbit supports **two authentication methods**:

<table><thead><tr><th>Method</th><th>Channels</th><th>Typical Use Cases</th><th data-hidden></th></tr></thead><tbody><tr><td><strong>OAuth 2.0 / 2.1</strong></td><td>REST API, MCP (remote HTTP)</td><td>Third-party app integrations, end-user delegated access, AI agent remote tool calls</td><td></td></tr></tbody></table>

### 2. Base URLs & Interactive References <a href="#heading-f20e82ae-0d17-4395-8fc6-21abfe6b1b51--20-base-urls-interactive-references-0" id="heading-f20e82ae-0d17-4395-8fc6-21abfe6b1b51--20-base-urls-interactive-references-0"></a>

Before issuing any request, make sure you are calling the correct endpoint. Orbit exposes two independent services, each with its own base URL and interactive documentation:

| Service        | Base URL                             | Interactive Reference                                                       | Description                                                                                                                        |
| -------------- | ------------------------------------ | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **MCP Server** | `https://mcp.orbitfin.ai/server/mcp` | `https://mcp.orbitfin.ai/docs` [<sup>2</sup>](https://mcp.orbitfin.ai/docs) | Streamable HTTP MCP endpoint for LLM clients (Claude Code, ChatGPT, Cursor, …) following the Model Context Protocol specification. |

**Quick Reference**

**MCP Server**

```
<HTTP>
Endpoint:         https://mcp.orbitfin.ai/server/mcp
Transport:        Streamable HTTP (MCP spec)
Docs:             https://mcp.orbitfin.ai/docs
Auth (API Key):   X-API-KEY: <your-api-key>
Auth (OAuth):     Authorization: Bearer <access_token>   ← see §3
```

**Minimal Smoke Tests**

Verify your key works against each surface in under 10 seconds.

**MCP Server — connect via JSON config**

```
{
  "mcpServers": {
    "orbit": {
      "url": "https://mcp.orbitfin.ai/server/mcp",
      "headers": {
        "X-API-KEY": "<your-api-key>"
      }
    }
  }
}
```

For the full list of MCP tools, resources, and prompt templates exposed by the server, browse the interactive catalog at `https://mcp.orbitfin.ai/docs` [<sup>2</sup>](https://mcp.orbitfin.ai/docs).

**Unified Billing Across Both Surfaces**

API Key usage on either surface draws from the **same credit pool** on your Orbit account:

Universal Currency: Same credits work for both APIs and MCP · APIs: Direct programmatic access charges credits per operation · MCP: Natural language queries consume credits based on complexity · Shared Pool: API and MCP usage draws from the same credit balance

. There is no need to provision separate quotas — a single API key (or a single OAuth-authenticated user, see §3) is billed uniformly.

<br>

### 3. Method 1: API Key Authentication <a href="#heading-17e4230e-4444-4c7c-bcc1-f83210b378ef--2-method-1-api-key-authentication-0" id="heading-17e4230e-4444-4c7c-bcc1-f83210b378ef--2-method-1-api-key-authentication-0"></a>

1. Sign in to the Orbit Console\[<https://insight.orbitfin.ai/>] → **Settings → API Keys**.

<figure><img src="/files/Q2qQEI3se4Oq8e2XVL7h" alt=""><figcaption></figcaption></figure>

2. Click **Create API Key**, give it a name, and save.

#### 3.2 Using API Key with MCP <a href="#heading-17e4230e-4444-4c7c-bcc1-f83210b378ef--23-using-api-key-with-mcp-0" id="heading-17e4230e-4444-4c7c-bcc1-f83210b378ef--23-using-api-key-with-mcp-0"></a>

For local stdio MCP clients or trusted environments:

**\<JSON>**

```
{
  "mcpServers": {
    "orbit": {
      "url": "https://mcp.orbitfin.ai/server/mcp",
      "headers": {
        "X-API-KEY": "<your-api-key>"
      }
    }
  }
}
```

#### 3.3 Security Best Practices <a href="#heading-17e4230e-4444-4c7c-bcc1-f83210b378ef--24-security-best-practices-0" id="heading-17e4230e-4444-4c7c-bcc1-f83210b378ef--24-security-best-practices-0"></a>

API keys are long-lived credentials that do not carry user identity, which makes per-user authorization difficult and creates significant risk if leaked into logs or version control; audit trails can only record what an API key did, not which user.

Therefore:

* **Never** embed API keys in frontend code.
* **Never** commit them to Git.
* **Rotate** keys regularly.
* Follow the **principle of least privilege** when assigning scopes (where supported).

### 4. Method 2: OAuth 2.0 Authentication (Recommended for MCP & Third-Party Apps) <a href="#heading-17e4230e-4444-4c7c-bcc1-f83210b378ef--3-method-2-oauth-20-authentication-recommended-for-mcp" id="heading-17e4230e-4444-4c7c-bcc1-f83210b378ef--3-method-2-oauth-20-authentication-recommended-for-mcp"></a>

#### 4.1 When to Use OAuth 2.0 <a href="#heading-17e4230e-4444-4c7c-bcc1-f83210b378ef--31-when-to-use-oauth-20-0" id="heading-17e4230e-4444-4c7c-bcc1-f83210b378ef--31-when-to-use-oauth-20-0"></a>

* Third-party SaaS applications integrating with Orbit.
* AI agents / LLM clients calling Orbit tools via remote MCP.
* Any scenario that requires **end-user identity** rather than application identity, with a complete audit trail.

#### 4.2 Calling the MCP with an Access Token <a href="#heading-17e4230e-4444-4c7c-bcc1-f83210b378ef--33-calling-the-api-with-an-access-token-0" id="heading-17e4230e-4444-4c7c-bcc1-f83210b378ef--33-calling-the-api-with-an-access-token-0"></a>

**\<JSON>**

```
{
  "mcpServers": {
    "orbit": {
      "url": "https://mcp.orbitfin.ai/server/mcp",
      "headers": {
        "Authorization": "Bearer <access_token>"
      }
    }
  }
}
```

#### 4.3 OAuth Configuration for the Remote MCP Server <a href="#heading-17e4230e-4444-4c7c-bcc1-f83210b378ef--34-oauth-configuration-for-the-remote-mcp-server-0" id="heading-17e4230e-4444-4c7c-bcc1-f83210b378ef--34-oauth-configuration-for-the-remote-mcp-server-0"></a>

When integrating with MCP-aware clients (Claude Desktop, ChatGPT, etc.), Orbit's MCP Server exposes the standard discovery endpoints:

* [`https://mcp.orbitfin.ai/.well-known/oauth-protected-resource`](https://mcp.orbitfin.ai/.well-known/oauth-authorization-server) — Resource metadata

On first connect, the client automatically discovers these endpoints and initiates the OAuth flow.

After the OAuth flow completes, the client attaches the obtained access token via the `Authorization: Bearer …` header on subsequent MCP requests. The server must treat the token as untrusted and perform full resource-server validation: signature verification, issuer/audience checks, expiration, replay protection, and scope enforcement.

#### 4.4 Connecting Orbit MCP in Claude Code & ChatGPT <a href="#heading-a084401b-d733-4c25-b6ad-16800c464428--36-connecting-orbit-mcp-in-claude-code-chatgpt-0" id="heading-a084401b-d733-4c25-b6ad-16800c464428--36-connecting-orbit-mcp-in-claude-code-chatgpt-0"></a>

Thanks to OAuth 2.0 + DCR, end users **do not need to manually create an API key or paste any token**. The entire setup is just three steps:

**▶ Claude Code**

1. Open **Claude Code → Settings → Connectors → Add Custom Connector**.
2. Fill in the form:
   * **Name**: any name you like, e.g. `Orbit`
   * **Remote MCP server URL**: <https://mcp.orbitfin.ai/server/mcp>
3. Click **Add**. Claude Code will automatically:
   * Discover Orbit's `.well-known` OAuth metadata,
   * Register itself via Dynamic Client Registration,
   * Open a browser window to the Orbit Insight login page.
4. Enter your **Insight platform username and password** to authorize.
5. Done ✅ — the Orbit tools are now available inside Claude Code.

> Example configuration (as shown in the screenshot):
>
> ```
> <TEXT>Name:                OrbitRemote MCP server URL: 
> https://mcp.orbitfin.ai/.well-known/oauth-protected-resource
> ```

**▶ ChatGPT**

1. Open **ChatGPT → Settings → Connectors → Create**(or **Add custom connector** in the Developer Mode panel).
2. Fill in:
   * **Name**: `Orbit` (or any name you prefer)
   * **MCP Server URL**: <https://mcp.orbitfin.ai/server/mcp>
   * **Authentication**: select **OAuth**
3. Click **Create / Connect**. ChatGPT will redirect you to the Orbit Insight login page.
4. Sign in with your **Insight platform username and password** to grant access.
5. Done ✅ — Orbit tools appear in ChatGPT's tool list and can be invoked in conversations.

**Why it's this simple**

* Orbit's MCP server publishes OAuth discovery metadata at\
  `https://mcp.orbitfin.ai/.well-known/oauth-protected-resource`
* Clients (Claude Code / ChatGPT) auto-register via **Dynamic Client Registration**, so no `client_id` / `client_secret` setup is required by the user.
* The user only authenticates **once** with their existing Insight account; refresh tokens keep the session alive.

<figure><img src="/files/H3zWPgYkA5ZyHbKBVqkO" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/adMXgX5oxfk44zOZ7c6z" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/pWBDoZc2Mj9kwB9cXGQP" alt=""><figcaption></figcaption></figure>