Substy API and MCP
Connect Claude, Claude Code, or Codex to your Substy agency.
Connect your agent
Use this production MCP server URL:
https://app.substy.ai/mcpAgency access
Production MCP access must be enabled for your agency. The REST API at api.substy.ai is a separate
interface; use the dashboard's /mcp URL for agent connections.
MCP uses browser sign-in and OAuth consent. You do not need a REST API key. Sign in to Substy, choose the agency, review the category permissions, and allow the access you want this connection to have. You can deny the request or reduce access instead of granting every category.
The connection remembers your approval. Your role, creator access, and the selected categories remain the limits on what the agent can do.
Claude web and desktop
- Open Settings → Connectors in Claude.
- Add a custom connector named Substy and paste the MCP server URL above.
- Connect and complete the Substy sign-in and consent screen in your browser.
- Choose the agency and category access, then return to Claude.
- Enable the Substy connector in your conversation and ask, “Which creators can I access in my agency?”
Connector availability depends on your Claude plan and workspace settings. Your organization may require an administrator to enable custom connectors.
Coding agents
Add the HTTP server to your user configuration:
claude mcp add --transport http --scope user substy https://app.substy.ai/mcpOpen Claude Code and run:
/mcpSelect Substy and authenticate in your browser. The --scope user option makes the server available across your projects. Omit that option if you want Claude Code’s default local scope instead.
Manage access
Choose the agency during consent. For another agency, approve a connection for that agency rather than expecting the agent to switch through an unapproved identifier. Read-only category grants allow queries; manage grants also allow the permitted actions.
If the agent reports that access is missing, check the agency and categories selected for the connection. Reconnect when you need to approve additional access or when the client’s authentication has expired. Repeated sign-in prompts for an already authorized action are not the intended flow.
Direct conversational replies to fans are unavailable. Scheduled and bulk messages, scripts, and AI controls are available within the categories you enable. Creator connection credentials are never returned to the agent.
Disconnect or reduce access
Use the Substy connection’s access settings to change category grants or disconnect the agency grant. You can also remove the connector from your client. Removing client configuration stops that client using it; do not assume it revokes a server-side grant or tokens in another client.
Troubleshooting
| What you see | What to check |
|---|---|
| An expired sign-in or consent request | Start a fresh connection from your agent and complete it promptly. |
| No tools after connecting | Confirm that authentication completed, the connector is enabled, and your agency has access. Refresh the client’s tool list or reconnect. |
| Additional permissions required | Check the selected agency and category grants; approve more access only if you want the requested action. |
| Repeated sign-in for an already authorized action | Start one fresh connection. If it repeats, report the non-sensitive error and request identifier to Substy. |
| Rate limit reached | Follow Retry-After. API and MCP calls share the agency budget. |
Documentation for agents
Give an agent the documentation index to discover guides and every API endpoint. Append .md to a guide or reference URL to retrieve its Markdown representation, for example /docs/mcp.md. The complete contract is available at /openapi.json.
These documentation URLs require no authentication. The authenticated Substy MCP server operates on agency data; this docs site does not expose a separate documentation MCP server.
Choose your interface
| REST API | MCP | |
|---|---|---|
| Best for | Software integrations and services | AI assistants and agent clients |
| Authentication | Substy-issued Clerk API key | OAuth sign-in and user consent |
| Input | URL parameters and JSON bodies | Typed tool arguments |
| Result | JSON data and request metadata | Agent-oriented tool results |
| Access | Agency key grants plus live user permissions | Connection grants plus live user permissions |
| Rate limits | Shared per agency | Same shared per-agency budget |
Both interfaces call the platform’s guarded operations. The REST API does not send requests through an MCP server, and the MCP protocol envelope is not part of the REST contract.
Use the API reference for REST names and request shapes. MCP tool names and discovery behavior are designed for agents and may differ from REST resource paths.
For MCP, your user chooses the agency and category access during connection. That choice is saved; the agent does not need a new sign-in for every tool call. Access can still be revoked or restricted by later role and membership changes.