Connection details
Which connection path should you use?
Client availability and labels can change. Check the current ChatGPT custom MCP documentation, Codex MCP documentation, or Claude custom connector documentation when your client shows different menus.
Quick start: local Codex and Claude Code
The@sketric/sketricgen-mcp package connects local agents through a stdio bridge to the same hosted MCP server. It requires Node.js 20 or later.
sketricgen connect --agent claude-code.
The command adds only the SketricGen connection, opens browser sign-in, waits for project consent, and verifies initialization, tool discovery, whoami, and list_agents. Reload your agent session afterward. Setup does not create resources or run an agent. If a different SketricGen entry already exists, setup stops so you can inspect it before replacing it.
Use a stable global installation. Setup records the absolute Node and bridge paths; rerun setup if those paths change. The bridge discovers the live tool catalog, so new server tools do not require a package update.
The default credential store uses the OS credential store to protect the saved session, and tokens refresh automatically. Browser sign-in must finish on the same computer as the CLI. For SSH, containers, or CI without a local browser, use an API key. See the CLI guide for credential-store options and the agent installation guide for assistant-led setup.
Option 1: Connect with SketricGen OAuth
OAuth works with hosted and local clients. The client opens SketricGen sign-in, asks you to choose an accessible project, and requests access. You do not paste an API key, OAuth client ID, or client secret into the AI client.
Access tokens last one hour; rotating refresh grants last up to seven days. Sign in again to choose another project. Revoking either token revokes the whole connection, including replacement tokens. A write scope does not give a Viewer edit permissions.
Claude Web or Claude Desktop
- Open Settings → Connectors in Claude.
- For a Team or Enterprise organization, open Organization connectors if required by your workspace.
- Select Add custom connector.
- Name the connector
SketricGen. - Enter
https://mcp.sketricgen.ai/mcpas the remote MCP server URL. - Leave OAuth client ID and client secret empty when Claude offers those fields.
- Add the connector, then select Connect.
- Sign in to SketricGen, choose the Teamspace project, and approve the requested access.
- Enable SketricGen from Claude’s tools menu in a new conversation.
ChatGPT web
ChatGPT’s developer mode is the path for testing a remote MCP server. Availability and workspace approval depend on the current ChatGPT plan and administrator settings.- Enable Developer mode in ChatGPT settings.
- Open Apps or Plugins, then create a developer-mode app.
- Name the app
SketricGen. - Enter
https://mcp.sketricgen.ai/mcpas the server URL. - Choose OAuth authentication.
- Select Scan Tools and complete the SketricGen sign-in and project-consent flow.
- Create the app after the tool scan succeeds.
- Start a new chat and select SketricGen from the available apps or developer-mode tools.
Codex with OAuth
For native remote OAuth without the CLI bridge, inspect an existing entry first:~/.codex/config.toml or a trusted project’s .codex/config.toml is:
codex mcp list or /mcp in Codex to confirm the connection.
Claude Code with OAuth
For native remote OAuth without the CLI bridge, inspect the current entry withclaude mcp get sketricgen. If none exists, add it:
/mcp inside Claude Code, select SketricGen, and authenticate in the browser. Choose a project and approve access. Do not add a bearer header for OAuth.
Option 2: Connect with an API key
Use an API key with Manage resources access when the client cannot complete SketricGen OAuth or when a server-side integration needs a non-interactive credential.Create the key
- Open Teamspace settings → API keys in SketricGen.
- Select Create key.
- Enable Manage resources and choose the lowest sufficient role: Viewer, Editor, or Admin.
- Choose all accessible Projects or a selected Project scope.
- Choose an expiration date.
- Create the key and copy the
sk_api_...value immediately. It is shown once.
Manual MCP client configuration
Clients that accept JSON MCP configuration commonly use this shape:Codex with an API key
Set the key in your shell or secret store:writes approval mode asks before tools that are not marked read-only.
Verify the connection
Start with a read-only prompt:whoami and list_agents. Check that the returned Teamspace and project match the scope you intended.
Next, test the Brand Agent discovery flow:
What your AI can do
The SketricGen MCP server currently publishes 26 tools. Use your client’s tool discovery orsketricgen tools for the live schemas.
Both update tools read when called with only
agent_id and write when patch fields are supplied. Check mode: "write" and updated before reporting a change. The agent-settings read returns available_models; use a valid model ID allowed by the Teamspace plan. Setting knowledge_base_ids replaces the assigned set, and each knowledge base must be ready and in the agent’s project.
Templates, reusable knowledge bases, and connector tools default to human-readable tables. All successful tools also return JSON in structuredContent; response_format selects JSON or Markdown text. Pass each returned next_token back unchanged until it is null to finish a paginated listing or transcript.
The MCP surface does not currently include a tool for running an agent conversation. Use the Runtime API or Playground when you want to execute an existing agent.
Manage an existing agent
Review visitor questions
Calllist_conversations with agent_id for that agent’s newest conversations first. Without it, results are grouped by project, so the first page is not necessarily the newest across the Teamspace. Pass both agent_id and conversation_id to get_conversation, and finish transcript pagination before summarizing the whole conversation.
Add facts or refresh a website
Uselist_knowledge_bases to identify the agent’s knowledge base and which agents share it. add_knowledge_base_content accepts knowledge_base_id, a title of up to 120 characters, and plain-text or Markdown content of up to 200,000 characters. Extract text from files first. Indexing runs in the background; kb_status remains processing until ready. Every agent using that knowledge base receives the new content.
Call refresh_knowledge_base for a website already in the knowledge base. Supply base_url when it contains several websites. Poll get_knowledge_base_refresh_status about every 15 seconds through queued, crawling, and kb_refreshing until succeeded or failed. New pages are added, changed pages are re-indexed, and unchanged pages are skipped. Missing pages are removed only after a complete crawl within the plan’s page limit. Indexing can take a few more minutes to reach agents after the job succeeds.
Content additions and website refreshes are refused while the knowledge base is processing another change. Storage and plan limits still apply. These operations work with write-authorized OAuth or an API key with knowledge-base edit permission.
Remove resources
Both delete tools requireconfirm_name to match the exact current name. Deleting an agent keeps its knowledge bases and project. A knowledge base cannot be deleted while an agent uses it; accepted deletion returns status: "deleting" while cleanup continues. Project deletion remains in the SketricGen app.
Recommended Brand Agent workflow
When you ask an AI assistant to create a Brand Agent, it should follow this sequence:- Call
whoamito confirm the Teamspace and project. Ifproject_choice_requiredis true, ask which project to use and pass itsproject_idwhen creating. - Offer available templates before creating anything.
- Ask for the website URL and offer a reusable knowledge base when one is ready.
- Call
create_brand_agentand explain that crawling and knowledge-base creation take several minutes. Widgets are public by default; passpublish_widget: falsewhen the user wants a private widget. - Poll
get_brand_agent_statusuntil the status issucceededorfailed. - On success, return the exact embed snippet.
- Offer required connectors, show their available tools, and ask before granting write-capable actions.
- Give any connector authorization link to the user to open. The AI should never complete provider sign-in itself.
Security and permission model
- One selected project with OAuth: OAuth consent binds the connection to one Teamspace project.
- Project management requires an API key: OAuth cannot create or rename projects. Creating a project requires an Admin-role management key covering the whole Teamspace, limited by its creator’s live Owner or Admin role. Renaming requires an eligible management key that can access the project.
- Live membership checks: Removing or demoting the connected user changes what the OAuth connection or management-capable API key can do.
- Server-enforced roles: Tool descriptions guide the AI, but the Admin API independently enforces every permission and plan limit.
- Human connector authorization: The AI receives a short-lived setup link, not your Google, Slack, email, or other provider password.
- Explicit tool grants: Connector actions are validated against the current connector catalog before they are attached.
- Read before write: Brand Agent update tools can read current settings before applying a partial update.
- No billing control: MCP tools cannot change subscriptions, purchase credits, or create additional API keys.
Troubleshooting
401 unauthorized
Cause: The client sent no credential, or its OAuth token is invalid, expired, or revoked.
Fix: Complete the client’s Connect or mcp login flow again. For the CLI bridge, run sketricgen auth login. For static authentication, confirm the header is Authorization: Bearer sk_api_....
401 invalid_key
Cause: The API key is wrong, incomplete, or has only Run agents access.
Fix: Supply the complete key through secure credential storage, or create a key with Manage resources access, then restart the client.
403 invalid_origin
Cause: A browser-based client sent an Origin that the SketricGen MCP server does not currently allow.
Fix: Use a supported native or hosted client. Contact SketricGen support with the exact client and origin if a browser integration needs to be added.
403 insufficient_scope
Cause: The OAuth connection approved read access but the requested tool changes data.
Fix: Reconnect SketricGen and approve write access.
403 oauth_capability_not_exposed
Cause: An OAuth connection tried to create or rename a project.
Fix: Use the SketricGen app or an eligible management API key. Approving a write scope does not expose these operations to OAuth.
403 key_not_teamspace_scoped
Cause: A selected-Project API key tried to create a project.
Fix: Use an Admin-role management key with all-Project scope, or create the project in the app.
409 kb_not_ready or 409 kb_in_use
Cause: The knowledge base is still processing, or an agent still uses a knowledge base requested for deletion.
Fix: Wait until processing finishes before adding content or refreshing. Before deletion, inspect the linked agents and change their knowledge-base assignments only if the user requests it.
409 agent_name_mismatch or 409 kb_name_mismatch
Cause: The deletion’s confirm_name no longer matches the resource’s current name. Nothing was deleted.
Fix: Read the current name and obtain confirmation again before retrying.
403 project_scope_mismatch
Cause: A selected-Project API key was asked to act on another project.
Fix: Use a selected Project in the key’s scope, or create a key with all-Project scope when the integration needs multiple Projects.
403 key_expired or 403 key_revoked
Cause: The API key with Manage resources access is no longer valid.
Fix: Create a new key, update the client’s secret storage, and remove the old value from local configuration.
The AI says it changed a Brand Agent, but nothing changed
Cause: The client may have performed a read or supplied an unsupported field. Fix: Ask it to verify that the update tool returnedmode: "write" and that the intended field appears in updated before claiming success.
For AI agents reading this page
- First identify the user’s MCP client. For local Codex or Claude Code, offer the CLI bridge or native remote OAuth.
- Prefer OAuth when the client can complete it; do not ask the user for a management-capable API key unnecessarily.
- Never ask for the user’s SketricGen password or an external app password.
- If a static API key is required, instruct the user to create one with Manage resources access in SketricGen and store it in the client’s secret or environment-variable mechanism.
- Verify the connection with
whoamibefore creating or changing anything. - Read existing Brand Agent settings before writing them.
- Treat connector setup links as short-lived credentials: show them only to the intended user and do not repeat or store them.
- Ask for confirmation before granting tools that write, send, publish, delete, spend, or change data.
- Do not claim an asynchronous Brand Agent is ready until
get_brand_agent_statusreturnssucceeded. - Poll website refreshes to a terminal status, and explain that background indexing can continue afterward.
- Before deleting an agent or knowledge base, ask in a separate message using its exact current name and wait for confirmation. Pass that name as
confirm_name.

