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

# MCP Guide

> Connect AI tools to Rings via the Model Context Protocol

## Rings MCP server

The Rings MCP server exposes tenant data to AI tools that support the [Model Context Protocol](https://modelcontextprotocol.io) (e.g. Claude, ChatGPT, Cursor). AI tools authenticate with your Rings account via OAuth 2.0 and can read and update data within what the authenticated user can already see and do in Rings. For server-side integrations, an API key may be used on MCP requests with the same tenant and rules as the REST API (see [Quickstart](/quickstart)).

<CardGroup cols={2}>
  <Card title="Server URL" icon="server">
    `https://production-api.joinrings.com/mcp`
  </Card>

  <Card title="Auth" icon="key">
    OAuth 2.0. Actions are performed on behalf of the authenticated user; access is scoped to the same data and permissions as in the Rings app.
  </Card>

  <Card title="Transport" icon="bolt">
    Streamable HTTP, **stateless** (no server-side MCP sessions).
  </Card>

  <Card title="ChatGPT app" icon="comments" href="https://chatgpt.com/apps/rings-ai/asdk_app_6a32575772f481918f88503de126c411">
    Install Rings AI in ChatGPT.
  </Card>
</CardGroup>

## Tools and this document

MCP **tools** are generated from the **`/v1` operations** defined in the OpenAPI document. Each tool maps to an HTTP method and path; parameters and bodies match the schemas in the [API Reference](/api-reference/introduction). For exact tool names and JSON schemas at runtime, use the MCP **`list_tools`** request in your client.

## What you can do with MCP today

| Area                  | Description                                                        |
| --------------------- | ------------------------------------------------------------------ |
| **Person**            | People, PathPower, incremental lists, recommended paths            |
| **Company**           | Orgs, affiliations, PathPower, incremental sync, recommended paths |
| **Opportunity**       | Deals, custom field mapping and values                             |
| **Activity**          | Email and meeting activity for persons and companies               |
| **Recommended paths** | Ranked contacts and multi-hop path context to a target             |
| **PathPower**         | Relationship strength scores for persons and companies             |
| **Note**              | Notes, rich content, entity associations                           |
| **Task**              | Tasks, assignees, due dates, reminders, associations               |
| **Users**             | Tenant users (e.g. to set per-user context)                        |
| **Meetings**          | Calendar meetings, date and participant filters                    |
| **AI summary**        | Cached AI summaries for persons and companies                      |
| **Entity List**       | Named collections of companies or persons and their membership     |
| **Relationships**     | Ring-wide and per-user relationships ranked by RQ/PathPower        |

## Connecting a client

<Steps>
  <Step title="Point your MCP client at the server URL">
    Configure your client (Claude, Cursor, or another MCP-compatible tool) with:

    ```text theme={null}
    https://production-api.joinrings.com/mcp
    ```
  </Step>

  <Step title="Authenticate">
    Sign in with OAuth 2.0 when prompted. For server-side integrations, send your API key in the `x-api-key` header on MCP requests — the same tenant, per-user context, and rate limiting rules apply as with the REST API.
  </Step>

  <Step title="Discover tools">
    Issue an MCP `list_tools` request to see the exact tool names and JSON schemas exposed by your tenant.
  </Step>

  <Step title="Call tools">
    Invoke tools from your AI client. Each call resolves to a REST endpoint under `/v1` and returns the same data shapes documented in the API Reference.
  </Step>
</Steps>

## Rate limiting

MCP calls the same REST API underneath. **Per-second and monthly** limits apply. Responses may include `429 Too Many Requests` and the usual rate-limit headers:

* `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset`
* `X-RateLimit-Limit-Monthly` / `X-RateLimit-Remaining-Monthly` / `X-RateLimit-Reset-Monthly`
* `Retry-After` on per-second exhaustion

<Tip>
  Implement exponential backoff and respect `Retry-After` when handling `429` responses.
</Tip>

## Use-case examples

<AccordionGroup>
  <Accordion title="Meeting prep" icon="calendar">
    From chat, load a person, recent activity, and upcoming meetings before a call.
  </Accordion>

  <Accordion title="Capture follow-ups" icon="list-check">
    Create tasks and notes via natural language (subject to tenant rules).
  </Accordion>

  <Accordion title="Relationship mapping" icon="diagram-project">
    Ask for PathPower or recommended paths before making an intro.
  </Accordion>

  <Accordion title="Create an opportunity" icon="handshake">
    List opportunity types, pick a type and one of its stages, then create the deal linked to a company or person.
  </Accordion>
</AccordionGroup>

## Per-user context

When using an API key with MCP, the same per-user context rules apply as the REST API:

* **Tenant-scoped keys** — pass `x-rings-user-id` with a user UUID to scope requests to that user. Omit it for tenant-wide data.
* **User-scoped keys** — the bound user is used automatically. If `x-rings-user-id` is provided, it must match the bound user or the request returns `403 Forbidden`.

See the [Quickstart](/quickstart) for full authentication details.