# Build with Onticord [Canonical page]() Connect your agent to Onticord, discover the tools available to a business, and request only the permissions your task needs. [OpenAPI 3.1 specification]() · [Agent connection guide]() · [Connect an agent]() ## Quickstart: no account or API key required The website documents and public onboarding guide are free to read without an account, API key, or sales conversation. Start with these read-only requests: ```sh curl --fail 'https://www.onticord.ai/openapi.json' curl --fail 'https://www.onticord.ai/developers.json' curl --fail 'https://auth.onticord.ai/llms.txt' ``` The OpenAPI document describes public HTTP reads and MCP tool discovery. Every operation has a unique operationId, description, and response schema. Public GET operations can be imported by HTTP function-calling clients; business tools use MCP and their live JSON Schemas. ## MCP endpoints and tool schemas Public onboarding MCP: [https://auth.onticord.ai/mcp](). This service provides setup guidance and exposes account-creation tools; it does not grant business access. Workspace MCP: [https://api.onticord.ai/api/mcp](). Use an MCP client with Streamable HTTP and OAuth support. Tool names, descriptions, inputSchema, and available outputSchema are returned by tools/list. Follow nextCursor when present. For a safe public discovery request, initialize the supported legacy protocol and then list the onboarding tools. Accept both JSON and SSE; parse the JSON-RPC data inside SSE frames. This stateless endpoint needs no session ID: ```sh curl --fail 'https://auth.onticord.ai/mcp' \ -H 'Content-Type: application/json' \ -H 'Accept: application/json, text/event-stream' \ --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"onticord-quickstart","version":"1.0.0"}}}' curl --fail 'https://auth.onticord.ai/mcp' \ -H 'Content-Type: application/json' \ -H 'Accept: application/json, text/event-stream' \ -H 'MCP-Protocol-Version: 2025-06-18' \ --data '{"jsonrpc":"2.0","method":"notifications/initialized"}' curl --fail 'https://auth.onticord.ai/mcp' \ -H 'Content-Type: application/json' \ -H 'Accept: application/json, text/event-stream' \ -H 'MCP-Protocol-Version: 2025-06-18' \ --data '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' ``` ## Authentication and least-privilege access Onticord uses OAuth access tokens for workspace MCP, rather than personal API keys. The human signs in, selects a business, and approves the exact delegated permissions. [Protected-resource metadata (RFC 9728)]() declares scopes\_supported and the authorization server. [Authorization-server metadata]() declares authorization, token, and client-registration endpoints. 1. Use the authorization-code flow with PKCE S256. Register your client through the published registration endpoint when your MCP client requires it. 2. Send resource=https://api.onticord.ai in authorization and token requests. Use your registered redirect URI and validate state. Never put client secrets or bearer tokens in public URLs. 3. Start with app.access for business reads and agent-connection verification. Request an additional scope only for the operation the human authorized. OAuth scopes constrain access; current business membership and human approval rules still apply. 4. Send Authorization: Bearer \ only to the workspace MCP endpoint. Use your MCP client's secure credential storage and refresh flow; a cookie or account alone is not workspace authorization. openid — Identify your account profile — View your name and profile email — View your email address offline\_access — Keep access when you are away app.access — Read workflows and business data; create, restart and verify the agent connection test for this business agent.sessions — Create and use your private Player 2 conversations in this business business.name — Change only this business's display name workflows.run — Start paid or live workflows in this business workflows.simulate — Simulate workflows using connected reads skills.draft — Prepare skill drafts for human installation connections.manage — Connect, reconnect, or disconnect business services connections.gorgias.request — Prepare Gorgias setup or workload detach for business owner review connections.mailbox.request — Prepare Gmail inbox setup, reconnect, or detach for human review and consent members.read — View members and invitation delivery status members.request — Prepare access changes for human confirmation triggers.read — View event triggers and eligible configurations triggers.manage — Disable triggers or prepare trigger creation for human confirmation packs.manage — Enable, configure, upgrade, or disable vertical packs effects.request — Prepare unknown external write reconciliation for human confirmation gates.redeliver — Retry delivery of an existing human decision notifications.manage — Change your own approval notification settings, link your matching Slack account, and send yourself a test billing.read — View your business’s subscription, usage, and invoices billing.manage — Change your business’s subscription and payment details ## Self-serve signup and first business request Start at [self-serve signup]() or [agent connection setup](). Follow the current connection guide for the sign-in methods enabled in your environment. An agent must not send sign-in email or create an account without the account holder's authorization. 1. After OAuth, discover workspace tools and call get\_agent\_connection\_setup. Follow its nextAction and verify the exact setup attempt with verify\_agent\_connection. 2. For a first commerce brief, use the current guide's read-only Commerce Intelligence flow. Check connected services and evidence coverage before claiming a result. 3. Do not start a paid workflow merely to test connectivity. Money, access changes, Skill installation, and required runtime approvals remain human decisions. ## Testing, sandbox, and pricing boundaries Use the public GET requests and onboarding tool discovery above to test your client's HTTP, JSON, and MCP parsing without credentials or customer data. This is public discovery, not a simulated merchant sandbox. A public hosted merchant sandbox, self-serve API-key issuance, and a general free usage tier are not currently offered here. Shopify installation is free; metered usage requires a separately approved Shopify plan. Signing in does not enable charges. Confirm the available plan and permissions in the hosted onboarding flow before live work. ## Errors and limits - 401 from workspace MCP means missing or invalid authorization. Read WWW-Authenticate and follow protected-resource discovery; do not retry the same invalid token indefinitely. - 403 means the request is not permitted. Check the origin, business membership, and required scopes instead of requesting broader access automatically. - 429 means rate limited. Honor Retry-After when supplied, otherwise use bounded exponential backoff with jitter. No universal requests-per-minute quota is promised by this documentation. - An HTTP 200 can still carry a JSON-RPC error or a tool result with isError. Inspect the protocol envelope and tool result. Do not blindly retry writes after a timeout. - GET on the public onboarding /mcp endpoint returns 405: it requires POST. Public onboarding request bodies are limited to 16 KiB. Browser access is restricted to trusted origins; use a supported MCP client for OAuth. [Support]() · [Privacy]() · [Terms]() [Agent instructions and connection guide]()