Loading documentation...
Preparing Ring content
Concepts, value, and typical clone scenarios — less code.
Concepts, value, and typical clone scenarios — less code.
Preparing Ring content
Preparing Ring content
Preparing Ring content
ring-mcp)Operate one Ring Platform clone from natural language — in Cursor, Claude Desktop, or any MCP host — without opening the admin UI for every CRUD task.
ring-mcp is a stdio MCP server under AI-RING/ring-mcp/. It does not open PostgreSQL. It calls your clone’s Bearer service gateway at /api/mcp/v1/*, which runs as a synthetic SUPERADMIN and reuses Ring’s existing services.
Use Founder / Developer tabs in the docs sidebar. Founders: how MCP and Telegram both remote-control your project. Developers: env, mcp.json, gateway paths, and tool inventory.
| Remote | Who uses it | How it reaches the clone |
|---|---|---|
| ring-mcp | Founders + hired developers in an AI IDE | stdio MCP → RING_API_BASE_URL + RING_MCP_ACCESS_KEY → /api/mcp/v1/* |
| Telegram Admin Bot | Admins on the phone | Whitelisted Telegram chat → webhook → Ring services (Manage via Telegram) |
They are sibling remotes, not the same process. Both target one white-label instance (your store, newsroom, users). Kingdom tools (legiox-*, ringdom-*, reggie-*) are a different scope.
You already have a Ring project (GreenFood, PetFriend, Vikka, …). You want to:
MCP is the IDE remote. Telegram is the phone remote. Point both at the same clone URL and keep tokens/secrets out of git.
Same-workflow: phone-side admin bot for the same clone ops surface.
See-also: kingdom MCP vs per-clone ring-mcp scope.
Deep-dive: ring-video-create end-to-end on the clone.
Next-step: ring-wiki-* tools for project knowledge self-build and search.
ring-mcp)Operate one Ring Platform clone from natural language — in Cursor, Claude Desktop, or any MCP host — without opening the admin UI for every CRUD task.
ring-mcp is a stdio MCP server under AI-RING/ring-mcp/. It does not open PostgreSQL. It calls your clone’s Bearer service gateway at /api/mcp/v1/*, which runs as a synthetic SUPERADMIN and reuses Ring’s existing services.
Use Founder / Developer tabs in the docs sidebar. Founders: how MCP and Telegram both remote-control your project. Developers: env, mcp.json, gateway paths, and tool inventory.
| Remote | Who uses it | How it reaches the clone |
|---|---|---|
| ring-mcp | Founders + hired developers in an AI IDE | stdio MCP → RING_API_BASE_URL + RING_MCP_ACCESS_KEY → /api/mcp/v1/* |
| Telegram Admin Bot | Admins on the phone | Whitelisted Telegram chat → webhook → Ring services (Manage via Telegram) |
They are sibling remotes, not the same process. Both target one white-label instance (your store, newsroom, users). Kingdom tools (legiox-*, ringdom-*, reggie-*) are a different scope.
You already have a Ring project (GreenFood, PetFriend, Vikka, …). You want to:
MCP is the IDE remote. Telegram is the phone remote. Point both at the same clone URL and keep tokens/secrets out of git.
Same-workflow: phone-side admin bot for the same clone ops surface.
See-also: kingdom MCP vs per-clone ring-mcp scope.
Deep-dive: ring-video-create end-to-end on the clone.
Next-step: ring-wiki-* tools for project knowledge self-build and search.
ring-mcp)Operate one Ring Platform clone from natural language — in Cursor, Claude Desktop, or any MCP host — without opening the admin UI for every CRUD task.
ring-mcp is a stdio MCP server under AI-RING/ring-mcp/. It does not open PostgreSQL. It calls your clone’s Bearer service gateway at /api/mcp/v1/*, which runs as a synthetic SUPERADMIN and reuses Ring’s existing services.
Use Founder / Developer tabs in the docs sidebar. Founders: how MCP and Telegram both remote-control your project. Developers: env, mcp.json, gateway paths, and tool inventory.
| Remote | Who uses it | How it reaches the clone |
|---|---|---|
| ring-mcp | Founders + hired developers in an AI IDE | stdio MCP → RING_API_BASE_URL + RING_MCP_ACCESS_KEY → /api/mcp/v1/* |
| Telegram Admin Bot | Admins on the phone | Whitelisted Telegram chat → webhook → Ring services (Manage via Telegram) |
They are sibling remotes, not the same process. Both target one white-label instance (your store, newsroom, users). Kingdom tools (legiox-*, ringdom-*, reggie-*) are a different scope.
You already have a Ring project (GreenFood, PetFriend, Vikka, …). You want to:
MCP is the IDE remote. Telegram is the phone remote. Point both at the same clone URL and keep tokens/secrets out of git.
Same-workflow: phone-side admin bot for the same clone ops surface.
See-also: kingdom MCP vs per-clone ring-mcp scope.
Deep-dive: ring-video-create end-to-end on the clone.
Next-step: ring-wiki-* tools for project knowledge self-build and search.
Same generative stack as ring-video-create on MCP.
1. Pick the clone URL
Local: http://localhost:3000. Production: https://your-clone.example.com. That becomes RING_API_BASE_URL — it must be your project, not another tenant.
2. Create one long random service token
On the Ring clone, set RING_MCP_ACCESS_KEY (comma-separated if you need several keys). Restart the app. Never commit the real value.
3. Register ring-mcp in Cursor
In kingdom .cursor/mcp.json (or Cursor Settings → MCP):
command: nodeargs: absolute path to AI-RING/ring-mcp/ring-mcp-server.jsenv: RING_API_BASE_URL, RING_MCP_ACCESS_KEY, optional RING_CLONE_NAME4. Smoke-test
Ask the agent: “Run ring-health and ring-whoami.” You should see your clone name and a superadmin service actor. Then try a read-only list (entities or opportunities).
5. Keep Telegram as the phone twin
Wire Manage via Telegram (ADMIN_BOT_*) separately. Same clone, different channel — whitelist only trusted Telegram chat IDs.
One clone → one MCP entry. Running GreenFood and PetFriend? Register two servers (e.g. ring-mcp-greenfood, ring-mcp-petfriend) with different URLs and tokens.
MCP runs as synthetic SUPERADMIN. Treat the access key like a root password. Prefer confirm-gated destructive tools (confirm: true) and audit who holds the key.
env.local.template| Variable | Required | Role |
|---|---|---|
RING_MCP_ACCESS_KEY | Yes | Comma-separated Bearer tokens accepted by the gateway |
RING_MCP_SERVICE_USER_ID | No | Synthetic actor id (default ring-mcp-service) |
RING_MCP_SERVICE_USER_EMAIL | No | Synthetic actor email |
RING_MCP_SERVICE_USER_NAME | No | Synthetic actor display name |
On ring-mcp (Cursor mcp.json env):
| Variable | Required | Role |
|---|---|---|
RING_API_BASE_URL | Yes | Clone origin (no trailing path) |
RING_MCP_ACCESS_KEY | Yes | Must match one token on the clone |
RING_CLONE_NAME | No | Label for ring-whoami |
Older docs mentioned RING_MCP_SERVICE_TOKENS. Gateway code reads RING_MCP_ACCESS_KEY only (lib/auth/service-token.ts).
Enable gateway on the clone
Restart Next.js after changing env.
Install & self-test
Register stdio server
Smoke
Or ask the agent to call ring-health + ring-whoami.
Register separate MCP entries (ring-mcp-connect, ring-mcp-platform, …) each with its own RING_API_BASE_URL + token. Do not reuse one token across production tenants.
Sensitive mutations require confirm: true.
| Domain | Tools (prefix ring-) |
|---|---|
| Meta | health, whoami |
| Entities | entity-list/get/search/create/update/delete |
| Opportunities | opportunity-* + opportunity-match |
| News | news-* + news-score/approve/reject + news-generate |
| Store | store-product-*, vendor-*, order-* |
| Users | user-* + user-set-role |
| Credit / payments | credit-*, payment-* |
| Notify / chat | notification-list, notify-send, fcm-send, conversation-list, message-send |
| Media | image-create, video-create |
Full parameter tables: ring-image-create, ring-video-create, generative newsroom.
| Path | Role |
|---|---|
app/api/mcp/v1/meta/ | health / whoami |
app/api/mcp/v1/entities/ … users/ … | Domain CRUD |
app/api/mcp/v1/images/generate | ImageConductor |
app/api/mcp/v1/videos/generate | VideoConductor |
app/api/mcp/v1/news/generate | TextConductor newsroom |
| Concern | ring-mcp | Telegram Admin Bot |
|---|---|---|
| Transport | MCP stdio + HTTP Bearer | Telegram webhook |
| Auth | RING_MCP_ACCESS_KEY | ADMIN_BOT_* + chat whitelist |
| Actor | Synthetic SUPERADMIN | Mapped Ring admin/superadmin user |
| Code | AI-RING/ring-mcp + app/api/mcp/v1 | lib/telegram/admin-bot/ |
| Docs | This page | Manage via Telegram |
Telegram does not spawn ring-mcp-server.js. Both eventually mutate the same clone data through Ring services.
| Symptom | Fix |
|---|---|
401 Invalid service token | Match MCP env token to clone RING_MCP_ACCESS_KEY; restart Ring |
RING_MCP_ACCESS_KEY is not configured | Set on Ring app, not only MCP |
tools: 0 / MCP missing in Cursor | Absolute path in mcp.json; run --test; reload MCP |
| Wrong clone data | Check RING_API_BASE_URL / RING_CLONE_NAME |
| Generative tools fail | Provider keys (XAI_API_KEY, …) on the clone, not in ring-mcp |
See-also: MDX authoring reference including RelatedArticle.
Same generative stack as ring-video-create on MCP.
1. Pick the clone URL
Local: http://localhost:3000. Production: https://your-clone.example.com. That becomes RING_API_BASE_URL — it must be your project, not another tenant.
2. Create one long random service token
On the Ring clone, set RING_MCP_ACCESS_KEY (comma-separated if you need several keys). Restart the app. Never commit the real value.
3. Register ring-mcp in Cursor
In kingdom .cursor/mcp.json (or Cursor Settings → MCP):
command: nodeargs: absolute path to AI-RING/ring-mcp/ring-mcp-server.jsenv: RING_API_BASE_URL, RING_MCP_ACCESS_KEY, optional RING_CLONE_NAME4. Smoke-test
Ask the agent: “Run ring-health and ring-whoami.” You should see your clone name and a superadmin service actor. Then try a read-only list (entities or opportunities).
5. Keep Telegram as the phone twin
Wire Manage via Telegram (ADMIN_BOT_*) separately. Same clone, different channel — whitelist only trusted Telegram chat IDs.
One clone → one MCP entry. Running GreenFood and PetFriend? Register two servers (e.g. ring-mcp-greenfood, ring-mcp-petfriend) with different URLs and tokens.
MCP runs as synthetic SUPERADMIN. Treat the access key like a root password. Prefer confirm-gated destructive tools (confirm: true) and audit who holds the key.
env.local.template| Variable | Required | Role |
|---|---|---|
RING_MCP_ACCESS_KEY | Yes | Comma-separated Bearer tokens accepted by the gateway |
RING_MCP_SERVICE_USER_ID | No | Synthetic actor id (default ring-mcp-service) |
RING_MCP_SERVICE_USER_EMAIL | No | Synthetic actor email |
RING_MCP_SERVICE_USER_NAME | No | Synthetic actor display name |
On ring-mcp (Cursor mcp.json env):
| Variable | Required | Role |
|---|---|---|
RING_API_BASE_URL | Yes | Clone origin (no trailing path) |
RING_MCP_ACCESS_KEY | Yes | Must match one token on the clone |
RING_CLONE_NAME | No | Label for ring-whoami |
Older docs mentioned RING_MCP_SERVICE_TOKENS. Gateway code reads RING_MCP_ACCESS_KEY only (lib/auth/service-token.ts).
Enable gateway on the clone
Restart Next.js after changing env.
Install & self-test
Register stdio server
Smoke
Or ask the agent to call ring-health + ring-whoami.
Register separate MCP entries (ring-mcp-connect, ring-mcp-platform, …) each with its own RING_API_BASE_URL + token. Do not reuse one token across production tenants.
Sensitive mutations require confirm: true.
| Domain | Tools (prefix ring-) |
|---|---|
| Meta | health, whoami |
| Entities | entity-list/get/search/create/update/delete |
| Opportunities | opportunity-* + opportunity-match |
| News | news-* + news-score/approve/reject + news-generate |
| Store | store-product-*, vendor-*, order-* |
| Users | user-* + user-set-role |
| Credit / payments | credit-*, payment-* |
| Notify / chat | notification-list, notify-send, fcm-send, conversation-list, message-send |
| Media | image-create, video-create |
Full parameter tables: ring-image-create, ring-video-create, generative newsroom.
| Path | Role |
|---|---|
app/api/mcp/v1/meta/ | health / whoami |
app/api/mcp/v1/entities/ … users/ … | Domain CRUD |
app/api/mcp/v1/images/generate | ImageConductor |
app/api/mcp/v1/videos/generate | VideoConductor |
app/api/mcp/v1/news/generate | TextConductor newsroom |
| Concern | ring-mcp | Telegram Admin Bot |
|---|---|---|
| Transport | MCP stdio + HTTP Bearer | Telegram webhook |
| Auth | RING_MCP_ACCESS_KEY | ADMIN_BOT_* + chat whitelist |
| Actor | Synthetic SUPERADMIN | Mapped Ring admin/superadmin user |
| Code | AI-RING/ring-mcp + app/api/mcp/v1 | lib/telegram/admin-bot/ |
| Docs | This page | Manage via Telegram |
Telegram does not spawn ring-mcp-server.js. Both eventually mutate the same clone data through Ring services.
| Symptom | Fix |
|---|---|
401 Invalid service token | Match MCP env token to clone RING_MCP_ACCESS_KEY; restart Ring |
RING_MCP_ACCESS_KEY is not configured | Set on Ring app, not only MCP |
tools: 0 / MCP missing in Cursor | Absolute path in mcp.json; run --test; reload MCP |
| Wrong clone data | Check RING_API_BASE_URL / RING_CLONE_NAME |
| Generative tools fail | Provider keys (XAI_API_KEY, …) on the clone, not in ring-mcp |
See-also: MDX authoring reference including RelatedArticle.
Same generative stack as ring-video-create on MCP.
1. Pick the clone URL
Local: http://localhost:3000. Production: https://your-clone.example.com. That becomes RING_API_BASE_URL — it must be your project, not another tenant.
2. Create one long random service token
On the Ring clone, set RING_MCP_ACCESS_KEY (comma-separated if you need several keys). Restart the app. Never commit the real value.
3. Register ring-mcp in Cursor
In kingdom .cursor/mcp.json (or Cursor Settings → MCP):
command: nodeargs: absolute path to AI-RING/ring-mcp/ring-mcp-server.jsenv: RING_API_BASE_URL, RING_MCP_ACCESS_KEY, optional RING_CLONE_NAME4. Smoke-test
Ask the agent: “Run ring-health and ring-whoami.” You should see your clone name and a superadmin service actor. Then try a read-only list (entities or opportunities).
5. Keep Telegram as the phone twin
Wire Manage via Telegram (ADMIN_BOT_*) separately. Same clone, different channel — whitelist only trusted Telegram chat IDs.
One clone → one MCP entry. Running GreenFood and PetFriend? Register two servers (e.g. ring-mcp-greenfood, ring-mcp-petfriend) with different URLs and tokens.
MCP runs as synthetic SUPERADMIN. Treat the access key like a root password. Prefer confirm-gated destructive tools (confirm: true) and audit who holds the key.
env.local.template| Variable | Required | Role |
|---|---|---|
RING_MCP_ACCESS_KEY | Yes | Comma-separated Bearer tokens accepted by the gateway |
RING_MCP_SERVICE_USER_ID | No | Synthetic actor id (default ring-mcp-service) |
RING_MCP_SERVICE_USER_EMAIL | No | Synthetic actor email |
RING_MCP_SERVICE_USER_NAME | No | Synthetic actor display name |
On ring-mcp (Cursor mcp.json env):
| Variable | Required | Role |
|---|---|---|
RING_API_BASE_URL | Yes | Clone origin (no trailing path) |
RING_MCP_ACCESS_KEY | Yes | Must match one token on the clone |
RING_CLONE_NAME | No | Label for ring-whoami |
Older docs mentioned RING_MCP_SERVICE_TOKENS. Gateway code reads RING_MCP_ACCESS_KEY only (lib/auth/service-token.ts).
Enable gateway on the clone
Restart Next.js after changing env.
Install & self-test
Register stdio server
Smoke
Or ask the agent to call ring-health + ring-whoami.
Register separate MCP entries (ring-mcp-connect, ring-mcp-platform, …) each with its own RING_API_BASE_URL + token. Do not reuse one token across production tenants.
Sensitive mutations require confirm: true.
| Domain | Tools (prefix ring-) |
|---|---|
| Meta | health, whoami |
| Entities | entity-list/get/search/create/update/delete |
| Opportunities | opportunity-* + opportunity-match |
| News | news-* + news-score/approve/reject + news-generate |
| Store | store-product-*, vendor-*, order-* |
| Users | user-* + user-set-role |
| Credit / payments | credit-*, payment-* |
| Notify / chat | notification-list, notify-send, fcm-send, conversation-list, message-send |
| Media | image-create, video-create |
Full parameter tables: ring-image-create, ring-video-create, generative newsroom.
| Path | Role |
|---|---|
app/api/mcp/v1/meta/ | health / whoami |
app/api/mcp/v1/entities/ … users/ … | Domain CRUD |
app/api/mcp/v1/images/generate | ImageConductor |
app/api/mcp/v1/videos/generate | VideoConductor |
app/api/mcp/v1/news/generate | TextConductor newsroom |
| Concern | ring-mcp | Telegram Admin Bot |
|---|---|---|
| Transport | MCP stdio + HTTP Bearer | Telegram webhook |
| Auth | RING_MCP_ACCESS_KEY | ADMIN_BOT_* + chat whitelist |
| Actor | Synthetic SUPERADMIN | Mapped Ring admin/superadmin user |
| Code | AI-RING/ring-mcp + app/api/mcp/v1 | lib/telegram/admin-bot/ |
| Docs | This page | Manage via Telegram |
Telegram does not spawn ring-mcp-server.js. Both eventually mutate the same clone data through Ring services.
| Symptom | Fix |
|---|---|
401 Invalid service token | Match MCP env token to clone RING_MCP_ACCESS_KEY; restart Ring |
RING_MCP_ACCESS_KEY is not configured | Set on Ring app, not only MCP |
tools: 0 / MCP missing in Cursor | Absolute path in mcp.json; run --test; reload MCP |
| Wrong clone data | Check RING_API_BASE_URL / RING_CLONE_NAME |
| Generative tools fail | Provider keys (XAI_API_KEY, …) on the clone, not in ring-mcp |
See-also: MDX authoring reference including RelatedArticle.