Connect to Orion MCP

With a single API token, an agent (Claude Code, Codex, and more) can call the tools and data in your workspace over MCP. No Orion CLI to install — the whole setup takes about 5 minutes.

How it works

The agent client connects to the server’s /mcp endpoint with Authorization: Bearer <token>. Orion returns the tools and data for the workspace bound to that token.

Third-party channel credentials (Gmail, LinkedIn, WhatsApp, and so on) live only in server-side connectors and are never handed to agents. An agent always receives a scoped Orion token.

Step 1: Get an API token

Ask your workspace admin to issue you an Orion API token. Tell them the minimal scopes you need:

["read", "write"]

Add these only if your agent needs to send messages or manage connections:

["send", "connect"]

The token is shown only once at creation — save it somewhere safe as soon as you receive it, and never commit it. Normal agents don’t need the admin scope.

Step 2: Install

Hand it to your agent (recommended)
Manual setup

Paste the token from Step 1 into the prompt below, then copy the whole block to your agent (Claude Code, Codex, and so on). It will register and verify the connection itself — no commands to type.

one-click install prompt

Set up the Orion MCP server in your runtime and verify the connection.

Connection details:
- Name: orion
- Transport: Streamable HTTP (type: http)
- URL: https://mcp-api.gracepeakglobal.com/mcp
- Auth header: Authorization: Bearer <PASTE_YOUR_ORION_TOKEN_HERE>

Do the following in order:
1. Register the MCP server above using your runtime's mechanism, authenticating with the Bearer token above:
   - Claude Code: claude mcp add --transport http orion "https://mcp-api.gracepeakglobal.com/mcp" --header "Authorization: Bearer <ORION_TOKEN>"
   - Codex: codex mcp add --url "https://mcp-api.gracepeakglobal.com/mcp" --header "Authorization: Bearer <ORION_TOKEN>"
   - Other clients: write it into their MCP config (type "http") with the same auth header.
2. After registering, restart the client (Codex / Claude Code) so the new MCP server takes effect.
3. After the restart, list orion's tools and confirm you can see whoami, list_cases, and so on.
4. Call whoami and tell me the workspace_id it returns, to confirm it's connected to my workspace.
5. If you get a 401 or 403, stop and tell me why (usually the token or auth header is wrong) — do not retry with other tokens.

This token is the credential for reaching Orion; you need it to authenticate when registering. Don't commit it to git or share it with anyone.

After it calls whoami, the agent reports the workspace_id. If it matches the workspace bound to your token, you’re set.

Prefer to control each step? Configure it by hand.

Set environment variables

export ORION_TOKEN="orn_xxxxxxxx"
export ORION_MCP_URL="https://mcp-api.gracepeakglobal.com/mcp"

Claude Code

Add it with one CLI command, or write it into a project-level .mcp.json:

claude mcp add --transport http orion "$ORION_MCP_URL" \
  --header 'Authorization: Bearer ${ORION_TOKEN}'

{
  "mcpServers": {
    "orion": {
      "type": "http",
      "url": "https://mcp-api.gracepeakglobal.com/mcp",
      "headers": {
        "Authorization": "Bearer ${ORION_TOKEN}"
      }
    }
  }
}

Codex

codex mcp add --url "$ORION_MCP_URL" \
  --header "Authorization: Bearer $ORION_TOKEN"

MCP Inspector

Fill in the endpoint and add one header in the connection form:

URL

https://mcp-api.gracepeakglobal.com/mcp

Header

Authorization: Bearer <ORION_TOKEN>

Restart and verify

When you’re done configuring, restart your client (Codex / Claude Code) so the new MCP server takes effect, then list the tools and call whoami:

tools/list
whoami

If the workspace_id returned by whoami matches the workspace bound to your token, you’re connected.

Troubleshooting

401 unauthorized

The token is missing, invalid, revoked, or expired. Reissue the token and check that the header is Authorization: Bearer ....

403 origin not allowed

A browser-like client sent an unlisted Origin. Add that origin to MCP_ALLOWED_ORIGINS; CLI clients usually don’t send an Origin.

429 rate limited

The client IP hit the rate limit. Reduce your request rate and retry.

connection refused

Wrong endpoint. Make sure you’re using https://mcp-api.gracepeakglobal.com/mcp.

tool error: forbidden

The token is missing the scope that tool requires. Reissue a token that includes the required scope.

Security rules

One API token is bound to one workspace.
Agents receive scoped Orion tokens, not third-party channel tokens.
Gmail, LinkedIn, WhatsApp, and other provider credentials stay in server-side connectors and are never handed to agents.
Dangerous tools require confirm: true and an idempotency key; clients must provide the parameters defined by each tool’s schema.

​How it works

​Step 1: Get an API token

​Step 2: Install

​Set environment variables

​Claude Code

​Codex

​MCP Inspector

​Restart and verify

​Troubleshooting

​Security rules

How it works

Step 1: Get an API token

Step 2: Install

Set environment variables

Claude Code

Codex

MCP Inspector

Restart and verify

Troubleshooting

Security rules