OnticordOnticord

Build with Onticord

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:

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:

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 <access_token> 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