> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbitsearch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect to Orbit with MCP

> Add the Orbit MCP server to Claude Code, Codex, Cursor, VS Code, and other agents with one command.

One command adds Orbit to your agent. Your agent can then search for people,
read source-backed profiles, enrich context, and manage directories.

## Install

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={"dark"}
    claude mcp add --transport http orbit https://api.orbitsearch.com/mcp
    ```

    Sign in to Orbit:

    ```bash theme={"dark"}
    claude mcp login orbit
    ```
  </Tab>

  <Tab title="Codex">
    ```bash theme={"dark"}
    codex mcp add orbit --url https://api.orbitsearch.com/mcp
    ```

    Sign in to Orbit:

    ```bash theme={"dark"}
    codex mcp login orbit
    ```
  </Tab>

  <Tab title="Cursor">
    Add Orbit to `~/.cursor/mcp.json`:

    ```json theme={"dark"}
    {
      "mcpServers": {
        "orbit": {
          "url": "https://api.orbitsearch.com/mcp"
        }
      }
    }
    ```

    Sign in to Orbit:

    ```bash theme={"dark"}
    agent mcp login orbit
    ```
  </Tab>

  <Tab title="VS Code">
    ```bash theme={"dark"}
    code --add-mcp '{"name":"orbit","type":"http","url":"https://api.orbitsearch.com/mcp"}'
    ```
  </Tab>

  <Tab title="Gemini CLI">
    ```bash theme={"dark"}
    gemini mcp add --transport http orbit https://api.orbitsearch.com/mcp
    ```
  </Tab>

  <Tab title="Claude Desktop">
    Open **Settings → Connectors → Add custom connector** and paste:

    ```
    https://api.orbitsearch.com/mcp
    ```
  </Tab>

  <Tab title="Other clients">
    Point any MCP client at the server URL over streamable HTTP:

    ```
    https://api.orbitsearch.com/mcp
    ```

    Clients that support remote OAuth sign you in on first use. Clients that
    support custom headers can use an [API key](#use-an-api-key-instead).
  </Tab>
</Tabs>

## Add the Orbit skills

Skills teach your agent how to get the most out of Orbit's tools. Install them
into Claude Code, Codex, Cursor, and 70+ other agents with the
[`npx skills`](https://github.com/vercel-labs/skills) CLI:

```bash theme={"dark"}
npx skills add orbit-search/orbit-mcp
```

This installs `orbit-directories`, which covers organization and directory
workflows in depth. Search, profile reads, and enrichment are covered by the
tool descriptions on this page.

## Use an API key instead

Sign-in works for every Orbit feature and needs no key. To use an API key,
create one in the [developer dashboard](https://developer.orbitsearch.com/dashboard/keys)
with the `search:read` and `profile:read` scopes, then pass it as a header:

<CodeGroup>
  ```bash Claude Code theme={"dark"}
  claude mcp add --transport http orbit https://api.orbitsearch.com/mcp \
    --header 'Authorization: Bearer ${ORBIT_API_KEY}'
  ```

  ```bash Codex theme={"dark"}
  codex mcp add orbit --url https://api.orbitsearch.com/mcp \
    --bearer-token-env-var ORBIT_API_KEY
  ```

  ```bash Gemini CLI theme={"dark"}
  gemini mcp add --transport http orbit https://api.orbitsearch.com/mcp \
    --header 'Authorization: Bearer ${ORBIT_API_KEY}'
  ```
</CodeGroup>

Keep the key in your shell environment or your client's secret store. See
[Authentication](/authentication) for scopes and rotation.

<Note>
  Directory management uses account sign-in, which applies your existing
  organization and directory permissions. Keys cover search, profile reads,
  and enrichment.
</Note>

## What you can do

| Tool             | Purpose                                                                       | Main inputs                                                                                       |
| ---------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `search_people`  | Find people and wait for v3 Search results.                                   | `query` and/or `signals`; optional `candidate_discovery`, `profile_depth`, `limit`, `request_id`. |
| `get_profile`    | Read the current person context. A read can schedule a refresh of stale data. | `profile_id` from a search result.                                                                |
| `enrich_profile` | Ensure a profile is partial or full, or request regeneration.                 | `profile_id`, `operation`, optional `request_id`.                                                 |

The catalog also includes directory tools such as `list_directories`,
`create_directory`, and `upload_directory_csv`.

## Search for people

`search_people` defaults to `candidate_discovery: false`, `profile_depth: "partial"`,
and `limit: 10`. The limit ranges from 1 to 20. Use a query, identity signals, or
both. Supported signals are `email`, `linkedin_url`, `usernames`, `urls`,
`address`, and `phone`.

```json theme={"dark"}
{
  "query": "Machine learning engineers in San Francisco",
  "candidate_discovery": false,
  "profile_depth": "partial",
  "limit": 1,
  "request_id": "people-search-001"
}
```

Use a returned `profile_id` with `get_profile` to read the profile again. This
read uses the [profile-read credit rate](/concepts/credits). Use `enrich_profile`
with `operation: "partial"` or `"full"` to request the profile depth you need.
`"regenerate"` requests fresh work; use it when you intend to refresh a profile.

<Warning>
  Search can build profiles. Enrich can build or regenerate profiles.
  `get_profile` reads the current person context.
</Warning>

## Manage directories

The MCP server supports creating and updating directories, member management,
directory-scoped search, CSV imports, source progress, access grants, one-time
refreshes, directory watchers, and activity feeds. Start with
`list_directory_organizations` and `list_directories` to choose your target.
See [Manage directories with MCP](/guides/mcp-directories) for workflows and limits.

Read and write permissions are separate: `directories.write` covers writes, and
`directories.read` covers reads. Your organization role and directory grants
still apply. Sign in again to pick up new permissions.

Use the REST API for batch enrichment, standalone watchers, and webhooks.

## Troubleshooting

* **Searches take a while.** Search and enrichment run until they reach a
  result. Allow long-running calls.
* **A call timed out.** Set a `request_id` before a search or enrichment call,
  then retry with that same ID and the same inputs to resume the same work.
* **HTTP 401.** Sign in again, or check that your key is present and current.
* **HTTP 403.** The session started with a different key. Reconnect with the
  key you intend to use.
* **Directory tools are missing.** Sign in again to grant directory access.
* **A search finished with `completed_with_errors`.** Keep the results it
  returned; they are valid.

See [Error handling](/guides/v3-error-handling) and
[Rate limits](/concepts/rate-limits) for the underlying API behavior.