scripts · servers
API key
Minted on the Developers page (Settings → Developers), scoped at creation — ads:read, catalog:write, or the read / write / admin bundles. Sent as a Bearer token on every call.
Authorization: Bearer mag_sk_live_…
// developers
Drive your whole store from your own AI.
Magistry exposes the same tool registry Otto uses — as a REST API and as a remote MCP server. Every tool is tagged read or write, every write follows the propose-then-approve model, and every call is scoped to exactly what you granted.
app.magistry.io/api/v1 MCP at /api/mcp 120 req/min
// auth
Two ways in. One safety model.
API keys for scripts and servers, OAuth 2.1 for MCP clients. Whichever you pick, writes go through the same approval model the rest of Magistry uses — nothing touches your store without a gate you configured.
mcp clients
OAuth 2.1
The MCP server ships a full authorization server with dynamic client registration. On connect you pick the store and the scopes — the client never sees more than you granted. Bearer API keys work here too.
https://app.magistry.io/api/mcp
writes
Approval-gated writes
Writes are either auto_write or propose_write. A propose_write returns an approval card the operator confirms in the dashboard. Auto-apply is opt-in, per credential, in Settings → Developers.
"status": "pending_approval"
// the tool registry
One registry. Otto's tools are your tools.
Every tool is invoked the same way: POST /api/v1/tools/{tool}. Each one is tagged read, write, or write-approval — the full catalog, with schemas, lives on your Developers page and in the OpenAPI document. A few examples:
READ
get_store_overview
Revenue, spend, profit, open approvals — the same overview the dashboard renders.
POST /api/v1/tools/get_store_overview
READ
query_products
Catalog state — lifecycle, tiers, cost confidence, per-product performance.
POST /api/v1/tools/query_products
READ
get_orders_summary
Order and revenue rollups over any window, per store.
POST /api/v1/tools/get_orders_summary
READ
query_performance
Daily performance series — spend, revenue, ROAS across channels.
POST /api/v1/tools/query_performance
WRITE · APPROVAL
propose_discount
Draft a discount campaign. Lands as an approval card the operator confirms.
POST /api/v1/tools/propose_discount
WRITE · APPROVAL
shopify_update_variant_price
Reprice a variant on Shopify. Approval-gated unless auto-apply is opted in.
POST /api/v1/tools/shopify_update_variant_price
// examples
curl it, or hand it to your AI.
The REST surface is one POST per tool with a Bearer key. The MCP server is the same registry over Streamable HTTP — connect Claude, Cursor, or any MCP client and your AI reads, analyses, and proposes against your live store.
restPOST
curl -X POST \
https://app.magistry.io/api/v1/tools/query_performance \
-H "Authorization: Bearer mag_sk_live_…" \
-H "Content-Type: application/json" \
-d '{ "days": 30 }'
# writes go through the same shape —
# propose_* returns an approval card,
# the operator confirms it in the dashboard
curl -X POST \
https://app.magistry.io/api/v1/tools/propose_discount \
-H "Authorization: Bearer mag_sk_live_…" \
-H "Content-Type: application/json" \
-d '{ "percent_off": 15, "product_ids": ["…"] }'mcpStreamable HTTP
// Claude Desktop — claude_desktop_config.json
{
"mcpServers": {
"magistry": {
"command": "npx",
"args": [
"mcp-remote",
"https://app.magistry.io/api/mcp"
]
}
}
}
// claude.ai → Settings → Connectors →
// Add custom connector →
// https://app.magistry.io/api/mcp
// OAuth picks your store + scopes on connect.// scopes
Grant exactly what the integration needs.
Scopes are fine-grained per resource + action, with read / write / admin bundles when you want the short version. Both surfaces are rate limited at 120 requests per minute per credential.
| Scope | Covers | Notes |
|---|---|---|
| read | Every read tool | Bundle — full reporting surface, no writes |
| write | Every write tool | Bundle — writes still follow the approval model |
| admin | Everything, including settings | Bundle — for trusted internal integrations only |
| ads:read · catalog:write · … | One resource, one action | Fine-grained — per resource + action, mix freely per key |
// connect your ai
Works with the AI you already use.
The MCP endpoint speaks standard Streamable HTTP, so anything that speaks MCP can drive your store — with the store and scope selection you approved, and nothing more.
Claude (claude.ai)Custom connector
Add the /api/mcp URL as a custom connector. OAuth walks you through store + scope selection.
app.magistry.io/api/mcp
Claude Desktopmcp-remote
One entry in claude_desktop_config.json via mcp-remote — the config is on the left of this page.
app.magistry.io/api/mcp
CursorMCP settings
Point Cursor's MCP settings at the remote endpoint and your editor can query the store mid-task.
app.magistry.io/api/mcp
Any MCP clientStreamable HTTP
Standard Streamable HTTP transport. OAuth 2.1 with dynamic client registration, or a Bearer API key.
app.magistry.io/api/mcp
// reference
The spec is the source of truth.
No hand-written docs that drift. The OpenAPI document is generated from the live tool registry, and the Developers page in your dashboard shows the exact catalog your credentials can reach.
OpenAPI document
The full REST surface — every tool, every input schema, every response shape — is published as an OpenAPI document. Point a generator or an agent at it and go.
GET https://app.magistry.io/api/v1/openapi.json
The Developers page
Settings → Developers in the dashboard is where keys live: mint and revoke API keys, pick scopes, browse the full tool catalog with its read / write / write-approval tags, and opt a credential into auto-apply.
- Mint scoped keys (mag_sk_live_…)
- Full tool catalog, tagged per tool
- Auto-apply opt-in, per credential
// developers
The same tools Otto uses. In your hands.
One registry powers Otto, the MCP server, and the REST API — same scopes, same approval model, same audit trail as everything else in Magistry.
Bearer API keys · OAuth 2.1 + dynamic client registration · Approval-gated writes · 120 req/min