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 (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).

Server URL

https://production-api.joinrings.com/mcp

Auth

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.

Transport

Streamable HTTP, stateless (no server-side MCP sessions).

ChatGPT app

Install Rings AI in ChatGPT.

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. 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

1. Point your MCP client at the server URL

   Configure your client (Claude, Cursor, or another MCP-compatible tool) with:

   https://production-api.joinrings.com/mcp
   
2. 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.

3. Discover tools

   Issue an MCP list_tools request to see the exact tool names and JSON schemas exposed by your tenant.

4. 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.

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

Implement exponential backoff and respect Retry-After when handling 429 responses.

Use-case examples

Meeting prep

From chat, load a person, recent activity, and upcoming meetings before a call.

Capture follow-ups

Create tasks and notes via natural language (subject to tenant rules).

Relationship mapping

Ask for PathPower or recommended paths before making an intro.

Create an opportunity

List opportunity types, pick a type and one of its stages, then create the deal linked to a company or person.

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 for full authentication details.