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

# Connect an agent

> Configure orriven's MCP server in Claude.ai, Claude Code, or any MCP-compatible client using OAuth 2.1 authentication.

The MCP server is accessible at a single HTTPS endpoint:

```text theme={null}
https://api.orriven.com/mcp
```

Clients discover authentication endpoints, register dynamically, and initiate the standard OAuth 2.1 authorization code flow with PKCE without requiring local binary installations.

## Add connector

<Tabs>
  <Tab title="Claude.ai">
    <Steps>
      <Step title="Open Settings → Connectors">
        Select **Add custom connector**.
      </Step>

      <Step title="Enter endpoint URL">
        Enter `https://api.orriven.com/mcp` and confirm. Claude dynamically registers with orriven and initiates the authorization redirect.
      </Step>

      <Step title="Authorize access">
        Sign in if prompted, review requested permissions, and select **Allow**. Enable the connector in target conversations.
      </Step>
    </Steps>
  </Tab>

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

    The initial tool call triggers the authorization flow in the default browser. In headless or remote environments, the CLI displays an authorization URL to open in any browser.

    Verify the connection status:

    ```bash theme={null}
    claude mcp list
    ```
  </Tab>

  <Tab title="Other clients">
    Any client supporting **Streamable HTTP** with **OAuth 2.1** (authorization code with PKCE and dynamic client registration) can connect directly—including Cursor, MCP Inspector, and applications using official MCP SDKs.

    Provide `https://api.orriven.com/mcp` to the client configuration. Stdio transport (local subprocess) is not supported; use the [command-line tool](/en/developers/cli) for local CLI workflows.
  </Tab>
</Tabs>

## Authorization consent

When a client connects for the first time with an account, orriven displays an authorization consent screen in the console.

<Frame caption="Authorization consent details: client identifier, verified redirect URI, and permission scope.">
  <div style={{ padding: "16px 20px", border: "1px solid #ddd", borderRadius: 8 }}>
    <strong>Claude</strong> requests access to orriven on behalf of <em>[user@example.com](mailto:user@example.com)</em>.<br />
    Redirect destination: <code>claude.ai</code><br />
    <small>Granting access delegates developer and organizational management permissions matching the authenticated user account.</small>
  </div>
</Frame>

Key verification points during authorization:

* **Authentication status**: Unauthenticated sessions require signing in via password or [enterprise SSO](/en/organization/members-roles) before completing authorization.
* **Redirect URI validation**: Verify the displayed redirect domain matches the client provider (`claude.ai` for Claude.ai, or `localhost` for local tools).
* **Consent action**: **Allow** completes authentication and issues an OAuth access token. **Deny** cancels the authorization request.

Authorization persists per client application and account. Subsequent sessions reuse the active credential until revocation or expiration.

<Warning>
  Only authorize requests initiated directly from your active session. Do not authorize requests originating from untrusted links or external messages.
</Warning>

## Initial workflow

After connection, query organizational structure to obtain resource identifiers:

1. **List organizations**: Invoke `list_organizations` to retrieve accessible organizations and roles.
2. **List Business Units**: Invoke `list_workspaces` with the target `organizationId` to retrieve Business Unit IDs.
3. **Provision API keys**: Invoke `create_api_key` or `create_publishable_key` with the target `workspaceId`.

```json theme={null}
// Example: create_api_key response
{
  "id": "key_101",
  "name": "staging-service",
  "keyId": "ok_3f9a8b1c",
  "secret": "osk_live_9a8b7c6d5e4f3a2b1c0d",
  "createdAt": "2026-08-28T09:00:00Z"
}
```

<Note>
  The plaintext API secret (`osk_…`) is returned **only once** in the initial tool response. Store this credential directly in a secure key management system or environment variable.
</Note>

## Disconnect

To remove an integration, delete the connector configuration within the client application (for example, in Claude.ai Connector Settings or by running `claude mcp remove orriven`).

Access tokens remain valid for 1 hour, renew automatically during active use, and expire after 7 days of inactivity. For full details on token lifecycle and revocation policies, see [Security & authorization](/en/agent/security).