Authentication
MCP requests authenticate with a dedicated, scoped credential — an MCP connection — through the same billing and workspace gates as the rest of the platform. An agent can never see more than the connection it authenticated as.
The MCP connection credential
An MCP connection is a revocable, least-privilege credential bound to one workspace and a set of scopes you choose. There are two ways to create one, and both end in the same kind of record you can see, rotate and revoke in Dashboard → Integrations → AI Connections:
- Dashboard token — create a connection, pick its workspace and scopes, and copy the
smcp_-prefixed bearer token. The token is shown once, expires after 90 days, and can be rotated or revoked from the same page at any time. - OAuth 2.1 — MCP clients that support OAuth (for example Claude’s custom connectors) discover Simplio3D’s authorization server automatically and run an authorization-code + PKCE flow with dynamic client registration. The consent page lets you pick the workspace and scopes to grant. OAuth access tokens last 8 hours and are refreshed automatically with rotating refresh tokens (60-day lifetime).
Authorization: Bearer smcp_YOUR_CONNECTION_TOKENTreat the token as a password. It grants access to everything its scopes cover in the workspace it is bound to. Store it in your MCP client’s secret input or an environment variable — never commit it to a repository, and never paste it into a chat. The SDK X-API-Key token is a different credential and is never accepted on the MCP endpoint (it remains valid for the REST/SDK routes it has always served).
Scopes
Every tool requires one scope; a connection only sees — and can only call — the tools its scopes cover. Tools, resources and prompts are all filtered to the granted scopes. The scope each tool requires is listed in the .
| Scope | Grants |
|---|---|
workspace:read | See the signed-in user, the workspace, its plan, billing status, seats and usage summary |
projects:read | List and inspect projects (structure, settings, health, share status, templates, saved configurations, proposed changes) |
projects:write | Create, rename, duplicate projects, import library assets, and change project settings (display, PDF, email routing, advanced) and quote-request triage |
assets:read | List assets, inspect 3D model structure (part names, hierarchy) and browse the curated + free asset libraries |
materials:read | List and read materials and material categories in the library |
materials:write | Create and edit materials and categories, import library or free textures, assign materials to variants |
configurator:read | Read option blocks, variants, selections, conditional logic and animations |
configurator:write | Create and edit option blocks, variants, modules, animations, conditional rules and block custom CSS |
pricing:read | Read pricing blocks and formulas, calculate prices |
pricing:write | Propose pricing, SKU and formula changes (each requires in-app approval) |
forms:read | Read quote/checkout form fields |
forms:write | Create and edit quote/checkout form fields |
quotes:read | Read submitted quote requests (customer leads) and the email activity log |
commerce:read | See whether Shopify/WooCommerce is connected and list store products |
commerce:write | Link a store product to a project and set the checkout mode (each requires in-app approval) |
workflows:read | Follow agent workflows: list workflow types and read workflow progress |
workflows:write | Operate agent workflows: start them, relay the user's answers to workflow questions, and pause / resume / cancel (high-risk changes still require in-app approval) |
docs:read | Search and read the official Simplio3D product documentation (no workspace data) |
Effective permission
A tool call succeeds only when all four layers allow it — the effective permission is the minimum of: the connection owner’s account authentication, the workspace seat role, the target workspace owner’s plan and billing state, and the connection’s scopes. A broad scope can never widen a narrow role, and vice versa.
| Requirement | Detail |
|---|---|
| Verified account | The email address on the connection owner’s account must be confirmed. |
| Plan & billing | The target workspace owner needs a Pro or Enterprise plan (or an active trial); Starter plans are blocked. An expired account receives HTTP 402 until a plan is activated; during the soft-lock grace period read tools keep working and write tools refuse. |
| Workspace role | Every tool declares the read or write permission it needs, enforced against the seat role on every call. A Viewer seat can never invoke or confirm a write. |
| Connection scopes | The tool’s scope must be among the scopes granted to the connection. |
Team workspaces
A connection is bound to one workspace — your own, or a team workspace you hold a seat in — chosen when the connection is created (or on the OAuth consent screen). Requests act on that workspace with the role you hold there. Your live seat is re-verified on every request rather than cached, so a seat that has been revoked, suspended, or downgraded stops working immediately.
The REST tool endpoint (which authenticates with a signed-in user’s access token rather than a connection) keeps its X-Workspace-Id header for acting inside a team workspace — the same live seat re-verification applies.