# onti agent signup and authentication Public onboarding MCP: https://auth.onticord.ai/mcp Workspace MCP (OAuth required): https://api.onticord.ai/api/mcp Guide: https://auth.onticord.ai/agents 1. Check which tools are actually available in this conversation. Reading this guide does not connect an MCP server or make its tools callable. If workspace tools are already connected, call get_agent_connection_setup and follow its nextAction; do not create another account. 2. If onti tools are unavailable, guide the human through adding the workspace MCP server https://api.onticord.ai/api/mcp with OAuth in their client. Use client_setup for the selected client or https://auth.onticord.ai/agents; show prerequisites and reachability before the handoff. Do not ask for a password in chat. If the client cannot add MCP connections, offer https://auth.onticord.ai/sign-up?mode=manual and explain that the agent connection remains pending. 3. Let the client start OAuth. The human signs in or chooses Create an account in the hosted login window, selects their workspace if asked, and decides Allow or Deny. Keep signup inside that window so the OAuth request survives. A copied prompt, created account, or successful sign-in alone does not prove an agent connection. 4. After the client completes OAuth, enable onti in the conversation and call get_agent_connection_setup. Follow nextAction: start setup if needed, then explicitly call verify_agent_connection with the discovered attempt.id as setup_id. Report the actual client and dated evidence returned. A generic read proves authenticated access but does not finish this check. If given an explicit expired or superseded setup_id, report its result and ask before restarting a different attempt; never silently substitute a newer ID. 5. Use onti's get_customer_rescue_readiness tool with no arguments to check my setup for one delayed-order investigation. Explain what is configured, what remains unverified, and the next action or operator handoff. Do not change setup or start an investigation from this check. Ask for an explicit investigation request and one order reference before starting a workflow. 6. For clients with public MCP or direct HTTP execution: call get_auth_guide, then request_sign_in_link with the owner's email and an optional business name. Tell the human to open the email, review the account action, and confirm to continue. Never read, redeem, or return the email token on their behalf. Account creation and OAuth approval remain pending until the human completes them. create_account is an optional legacy password path. 7. For a custom MCP client, discover the issuer, register a public client (token_endpoint_auth_method: none), and use authorization_code with S256 PKCE, random state, and oauth_resource. Request openid and app.access for workspace reads; include offline_access if refresh is needed. Open authorization for the human's sign-in, workspace choice and consent, then exchange the callback code using the original code_verifier and redirect_uri. Store OAuth tokens in the client's credential store. ## Connection details and requirements { "public_mcp_url": "https://auth.onticord.ai/mcp", "workspace_mcp_url": "https://api.onticord.ai/api/mcp", "documentation_url": "https://auth.onticord.ai/agents", "text_documentation_url": "https://auth.onticord.ai/llms.txt", "onboarding_url": "https://auth.onticord.ai/onboarding", "signup_url": "https://auth.onticord.ai/sign-up", "manual_signup_url": "https://auth.onticord.ai/sign-up?mode=manual", "signin_url": "https://auth.onticord.ai/sign-in", "panel_url": "https://panel.onticord.ai", "magic_link_api_url": "https://auth.onticord.ai/api/auth/sign-in/magic-link", "default_authentication": "magic-link", "sign_in_options": { "shopify": false, "google": false, "apple": false, "microsoft": false, "github": false }, "shopify": { "human_signin_url": "https://auth.onticord.ai/sign-in", "instructions": "When available, the human chooses Continue with Shopify in the hosted OAuth window. Shopify owns store selection and installation. The verified store owner creates one store-linked business; staff need an existing onti membership. Preserve the signed OAuth request and let the human approve agent access afterward. Never request Shopify passwords, ID tokens, or API tokens through MCP. A store-linked business is not proof that commerce API credentials are connected.", "pricing": "Free to install; usage billing requires a separately approved Shopify plan. Sign-in does not enable charges." }, "signup_api_url": "https://auth.onticord.ai/api/auth/sign-up/email", "signin_api_url": "https://auth.onticord.ai/api/auth/sign-in/email", "authorization_server_metadata_url": "https://auth.onticord.ai/.well-known/oauth-authorization-server/api/auth", "protected_resource_metadata_url": "https://api.onticord.ai/.well-known/oauth-protected-resource", "oauth_resource": "https://api.onticord.ai", "protocol_version": "2026-07-28", "connection_setup": { "discover_tool": "get_agent_connection_setup", "start_tool": "start_agent_connection_setup", "restart_tool": "restart_agent_connection_setup", "verify_tool": "verify_agent_connection", "instructions": "After OAuth, discover the current setup and follow nextAction. Use attempt.id as setup_id for explicit verification. Generic reads show authenticated access but never complete setup. Restart only the exact expired or conflicting attempt requested; never silently substitute a newer ID. These tools require app.access and current business membership, and do not start paid workflows." }, "delegated_scope_policy": "app.access permits business reads and onboarding proof. Explicitly request workflows.run, workflows.simulate, skills.draft, connections.manage, packs.manage, members.read, members.request, triggers.read, triggers.manage, effects.request, gates.redeliver, or notifications.manage for those operations. Current member authority is always checked. Approval, installation, and access changes still require a human decision.", "transport": "Streamable HTTP; stateless, request-scoped SSE; legacy 2025 clients supported", "client_setup": { "chatgpt": { "id": "chatgpt", "name": "ChatGPT", "mark": "GPT", "label": "USE YOUR ACCOUNT", "color": "#7DDDC3", "note": "On ChatGPT web, with Developer mode turned on.", "url": "https://chatgpt.com/", "docs": "https://developers.openai.com/plugins/deploy/connect-chatgpt", "guideAnchor": "chatgpt", "surface": "Set up in ChatGPT web. Resume these instructions on your computer if needed.", "prerequisites": [ "Developer mode must be available for your account and workspace policy. Ask your workspace administrator if it is unavailable." ], "networkRequirement": "ChatGPT needs a public HTTPS MCP endpoint or an explicitly configured Secure MCP Tunnel. Pasting localhost does not create a tunnel. onti does not provision one here.", "add": [ "In ChatGPT web, open Settings → Security and login and enable Developer mode.", "Open Plugins and select the plus button. Name the connection onti. For a public connection, enter https://api.onticord.ai/api/mcp as the MCP server URL and use OAuth. If you already have a Secure MCP Tunnel configured, use its documented Tunnel connection instead." ], "authorize": "In the onti window, sign in or create your account. Review and confirm any emailed account action yourself, select the intended business, and decide whether to allow access. Keep this OAuth window open through signup. Never share passwords, email links or tokens in chat.", "enable": "Start a new ChatGPT conversation. Open its tools menu and add the onti MCP connection before sending the connection-check prompt.", "guide_url": "https://auth.onticord.ai/agents#chatgpt", "mcp_url": "https://api.onticord.ai/api/mcp", "authentication": "OAuth", "documentation_url": "https://developers.openai.com/plugins/deploy/connect-chatgpt", "documentation_checked_at": "2026-09-07", "client_validation": "not_run", "steps": [ "In ChatGPT web, open Settings → Security and login and enable Developer mode.", "Open Plugins and select the plus button. Name the connection onti. For a public connection, enter https://api.onticord.ai/api/mcp as the MCP server URL and use OAuth. If you already have a Secure MCP Tunnel configured, use its documented Tunnel connection instead.", "In the onti window, sign in or create your account. Review and confirm any emailed account action yourself, select the intended business, and decide whether to allow access. Keep this OAuth window open through signup. Never share passwords, email links or tokens in chat.", "Start a new ChatGPT conversation. Open its tools menu and add the onti MCP connection before sending the connection-check prompt.", "Call get_agent_connection_setup and follow its nextAction. If needed, call start_agent_connection_setup, then explicitly call verify_agent_connection with setup.attempt.id from the successful result as setup_id. Reading business data alone does not complete this connection check. Report the actual OAuth client and dated evidence. If an explicit setup_id is expired or superseded, explain the result; never silently verify a replacement." ] }, "claude": { "id": "claude", "name": "Claude", "mark": "✳", "label": "USE YOUR ACCOUNT", "color": "#E7AC8E", "note": "Added as a custom connector. On a team plan, an owner adds it first.", "url": "https://claude.ai/", "docs": "https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp", "guideAnchor": "claude", "surface": "Set up in Claude web. Resume these instructions on your computer if needed.", "prerequisites": [ "Individual Pro/Max accounts can add a custom connector. For Team/Enterprise, an Owner or Primary Owner must add it for the organization before members connect." ], "networkRequirement": "Claude remote connectors run from Anthropic infrastructure, including desktop and mobile. The endpoint must be reachable from that infrastructure; localhost, VPN-only or private-network access from your own device is insufficient.", "add": [ "Individual account: open Customize → Connectors → + → Add custom connector. Name it onti and enter https://api.onticord.ai/api/mcp.", "Team/Enterprise owner: open Organization settings → Connectors → Add → Custom → Web and add https://api.onticord.ai/api/mcp. Then each member opens Customize → Connectors, finds onti, and selects Connect to authenticate." ], "authorize": "In the onti window, sign in or create your account. Review and confirm any emailed account action yourself, select the intended business, and decide whether to allow access. Keep this OAuth window open through signup. Never share passwords, email links or tokens in chat.", "enable": "In the Claude conversation, open + at the lower left, select Connectors, and turn on onti before sending the connection-check prompt.", "guide_url": "https://auth.onticord.ai/agents#claude", "mcp_url": "https://api.onticord.ai/api/mcp", "authentication": "OAuth", "documentation_url": "https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp", "documentation_checked_at": "2026-09-07", "client_validation": "not_run", "steps": [ "Individual account: open Customize → Connectors → + → Add custom connector. Name it onti and enter https://api.onticord.ai/api/mcp.", "Team/Enterprise owner: open Organization settings → Connectors → Add → Custom → Web and add https://api.onticord.ai/api/mcp. Then each member opens Customize → Connectors, finds onti, and selects Connect to authenticate.", "In the onti window, sign in or create your account. Review and confirm any emailed account action yourself, select the intended business, and decide whether to allow access. Keep this OAuth window open through signup. Never share passwords, email links or tokens in chat.", "In the Claude conversation, open + at the lower left, select Connectors, and turn on onti before sending the connection-check prompt.", "Call get_agent_connection_setup and follow its nextAction. If needed, call start_agent_connection_setup, then explicitly call verify_agent_connection with setup.attempt.id from the successful result as setup_id. Reading business data alone does not complete this connection check. Report the actual OAuth client and dated evidence. If an explicit setup_id is expired or superseded, explain the result; never silently verify a replacement." ] }, "cursor": { "id": "cursor", "name": "Cursor", "mark": "↗", "label": "USE YOUR ACCOUNT", "color": "#C4CCFF", "note": "Set up in Cursor on your computer, alongside anything you already use.", "url": "https://cursor.com/docs/mcp", "docs": "https://cursor.com/docs/mcp", "guideAnchor": "cursor", "surface": "Use Cursor on the computer where you want the connection. The manual path below configures your user account, not a cloud agent or every teammate.", "prerequisites": [ "Your Cursor configuration and team policy must allow this MCP server. A local agent can prepare the exact configuration change for you to review." ], "networkRequirement": "Cursor supports Streamable HTTP with OAuth. A local endpoint requires Cursor to run on the same computer; web or cloud agents need their own reachable endpoint.", "add": [ "For an existing ~/.cursor/mcp.json, add only the server entry below inside mcpServers. Use the new-file example only when that file does not exist.", "Open Customize in the Cursor sidebar to find and enable the server. Complete the OAuth flow Cursor presents for the server; if no sign-in prompt appears, use the official Cursor guide to check this server's setup. This guide provides manual configuration, not a marketplace installation." ], "authorize": "In the onti window, sign in or create your account. Review and confirm any emailed account action yourself, select the intended business, and decide whether to allow access. Keep this OAuth window open through signup. Never share passwords, email links or tokens in chat.", "enable": "Enable onti in Customize, then open Agent chat and check that its tools appear under Available Tools. Send the connection-check prompt there; keep required tool approvals enabled.", "config": { "entry": "{\n \"onticord\": {\n \"url\": \"https://api.onticord.ai/api/mcp\"\n }\n}", "newFile": "{\n \"mcpServers\": {\n \"onticord\": {\n \"url\": \"https://api.onticord.ai/api/mcp\"\n }\n }\n}", "guidance": "Preserve all other servers, settings, comments and environment references. If onticord already has this URL, reuse it. If it differs, prepare an exact change and obtain the human's installation/access decision before replacing it. If the file cannot be parsed safely, stop and explain the problem. Do not overwrite it, paste its secrets into chat, add tokens to this example, or disable approvals. A prepared change must still match the current file before it is applied." }, "guide_url": "https://auth.onticord.ai/agents#cursor", "mcp_url": "https://api.onticord.ai/api/mcp", "authentication": "OAuth", "documentation_url": "https://cursor.com/docs/mcp", "documentation_checked_at": "2026-09-07", "client_validation": "not_run", "steps": [ "For an existing ~/.cursor/mcp.json, add only the server entry below inside mcpServers. Use the new-file example only when that file does not exist.", "Open Customize in the Cursor sidebar to find and enable the server. Complete the OAuth flow Cursor presents for the server; if no sign-in prompt appears, use the official Cursor guide to check this server's setup. This guide provides manual configuration, not a marketplace installation.", "In the onti window, sign in or create your account. Review and confirm any emailed account action yourself, select the intended business, and decide whether to allow access. Keep this OAuth window open through signup. Never share passwords, email links or tokens in chat.", "Enable onti in Customize, then open Agent chat and check that its tools appear under Available Tools. Send the connection-check prompt there; keep required tool approvals enabled.", "Call get_agent_connection_setup and follow its nextAction. If needed, call start_agent_connection_setup, then explicitly call verify_agent_connection with setup.attempt.id from the successful result as setup_id. Reading business data alone does not complete this connection check. Report the actual OAuth client and dated evidence. If an explicit setup_id is expired or superseded, explain the result; never silently verify a replacement." ] }, "custom": { "id": "custom", "name": "Your agent", "mark": "{ }", "label": "BRING YOUR OWN", "color": "#A6C8FF", "note": "Any agent you run yourself that can connect to remote tools and sign in.", "url": "/agents#your-agent", "docs": "/agents#your-agent", "guideAnchor": "your-agent", "surface": "Use the settings of the client you manage, including self-managed Hermes or OpenClaw. Resume on the device running that client when needed.", "prerequisites": [ "The client must support Streamable HTTP and OAuth, and securely store its own credentials. A web reader cannot install tools just by opening this guide." ], "networkRequirement": "The machine running your client must reach the MCP and authentication endpoints. Local-only clients may require a separately configured compatible bridge; none is installed by this guide.", "add": [ "Add a remote MCP server named onti using https://api.onticord.ai/api/mcp, Streamable HTTP transport and OAuth authentication. Follow your client's documentation to start its OAuth flow." ], "authorize": "In the onti window, sign in or create your account. Review and confirm any emailed account action yourself, select the intended business, and decide whether to allow access. Keep this OAuth window open through signup. Never share passwords, email links or tokens in chat.", "enable": "Enable the onti server and its tools in the conversation using your client's documented controls. Check that the onti tools are available before sending the connection-check prompt.", "guide_url": "https://auth.onticord.ai/agents#your-agent", "mcp_url": "https://api.onticord.ai/api/mcp", "authentication": "OAuth", "documentation_url": "https://auth.onticord.ai/agents#your-agent", "documentation_checked_at": "2026-09-07", "client_validation": "not_run", "steps": [ "Add a remote MCP server named onti using https://api.onticord.ai/api/mcp, Streamable HTTP transport and OAuth authentication. Follow your client's documentation to start its OAuth flow.", "In the onti window, sign in or create your account. Review and confirm any emailed account action yourself, select the intended business, and decide whether to allow access. Keep this OAuth window open through signup. Never share passwords, email links or tokens in chat.", "Enable the onti server and its tools in the conversation using your client's documented controls. Check that the onti tools are available before sending the connection-check prompt.", "Call get_agent_connection_setup and follow its nextAction. If needed, call start_agent_connection_setup, then explicitly call verify_agent_connection with setup.attempt.id from the successful result as setup_id. Reading business data alone does not complete this connection check. Report the actual OAuth client and dated evidence. If an explicit setup_id is expired or superseded, explain the result; never silently verify a replacement." ] } }, "reachability": { "guide_and_auth": { "kind": "https", "message": "HTTPS endpoint: client reachability has not been checked. The MCP server, authentication pages and discovery URLs must all be reachable from the client that uses them." }, "workspace_mcp": { "kind": "https", "message": "HTTPS endpoint: client reachability has not been checked. The MCP server, authentication pages and discovery URLs must all be reachable from the client that uses them." }, "instructions": "A guide fetch does not install tools. A local URL refers to the machine using it, not the merchant's other device. Do not invent a public endpoint, configure a tunnel, or claim compatibility from these instructions. Follow the selected client's network requirements." }, "device_handoff": { "instructions": "Copy only the guide/step navigation link offered by onti and sign in on the destination device. It restores instructions, not credentials or an OAuth transaction. Review the intended business there. Discover current setup after the destination client completes its own OAuth flow; do not silently restart a different attempt. Local-only auth pages cannot be resumed from another device using localhost." }, "customer_rescue": { "readiness_tool": "get_customer_rescue_readiness", "required_scope": "app.access", "arguments": {}, "instructions": "Use onti's get_customer_rescue_readiness tool with no arguments to check my setup for one delayed-order investigation. Explain what is configured, what remains unverified, and the next action or operator handoff. Do not change setup or start an investigation from this check. Ask for an explicit investigation request and one order reference before starting a workflow." }, "signup": { "required": [ "email" ], "preferred_tool": "request_sign_in_link", "confirmation": "The human opens the emailed link, reviews the masked destination and account action, and confirms to continue. Links expire in 10 minutes and work once. A password can be set later at /reset-password.", "optional": [ "name", "organizationName" ], "password_min_length": 8, "password_max_length": 128, "organization": "Every new account gets one Better Auth organization with owner membership. organizationName is optional (at most 100 characters; blank uses the default); do not ask for a workspace type or require a name. Existing users sign in to their current memberships; staff join other organizations by accepting an invitation." }, "direct_http": { "content_type": "application/json", "magic_link_body": { "email": "owner@example.com", "name": "Owner", "callbackURL": "/onboarding" }, "signup_body": { "email": "your-agent@example.com", "password": "", "name": "Your agent" }, "signup_required": [ "email", "password", "name" ], "signin_body": { "email": "your-agent@example.com", "password": "" }, "session_handling": "Retain Set-Cookie in a private cookie jar. Public MCP intentionally does not return these credentials; use direct HTTP signup/signin if your client needs a session without a browser.", "register_url": "https://auth.onticord.ai/api/auth/oauth2/register", "register_body": { "client_name": "Your agent", "redirect_uris": [ "http://127.0.0.1:9999/callback" ], "grant_types": [ "authorization_code", "refresh_token" ], "response_types": [ "code" ], "token_endpoint_auth_method": "none", "application_type": "native" }, "authorize_url": "https://auth.onticord.ai/api/auth/oauth2/authorize", "authorize_query": "client_id, response_type=code, redirect_uri, scope=openid offline_access app.access, random state, code_challenge=BASE64URL(SHA256(code_verifier)), code_challenge_method=S256, resource=oauth_resource", "human_authorization": "Open the original authorization URL for the human to sign in, select the business and review access. Follow the hosted flow without manufacturing consent or copying its review credentials into MCP. Only the human submits the displayed decision; the client resumes at its registered callback. Do not POST business selection or consent on the human's behalf.", "token_url": "https://auth.onticord.ai/api/auth/oauth2/token", "token_form": "application/x-www-form-urlencoded: grant_type=authorization_code, client_id, code, redirect_uri, code_verifier, resource=oauth_resource", "callback_handling": "Do not blindly follow redirects. Validate callback origin/path against your registered redirect_uri and state against your original random state before exchanging its code. Keep callback codes and tokens private." }, "steps": [ "Check which tools are actually available in this conversation. Reading this guide does not connect an MCP server or make its tools callable. If workspace tools are already connected, call get_agent_connection_setup and follow its nextAction; do not create another account.", "If onti tools are unavailable, guide the human through adding the workspace MCP server https://api.onticord.ai/api/mcp with OAuth in their client. Use client_setup for the selected client or https://auth.onticord.ai/agents; show prerequisites and reachability before the handoff. Do not ask for a password in chat. If the client cannot add MCP connections, offer https://auth.onticord.ai/sign-up?mode=manual and explain that the agent connection remains pending.", "Let the client start OAuth. The human signs in or chooses Create an account in the hosted login window, selects their workspace if asked, and decides Allow or Deny. Keep signup inside that window so the OAuth request survives. A copied prompt, created account, or successful sign-in alone does not prove an agent connection.", "After the client completes OAuth, enable onti in the conversation and call get_agent_connection_setup. Follow nextAction: start setup if needed, then explicitly call verify_agent_connection with the discovered attempt.id as setup_id. Report the actual client and dated evidence returned. A generic read proves authenticated access but does not finish this check. If given an explicit expired or superseded setup_id, report its result and ask before restarting a different attempt; never silently substitute a newer ID.", "Use onti's get_customer_rescue_readiness tool with no arguments to check my setup for one delayed-order investigation. Explain what is configured, what remains unverified, and the next action or operator handoff. Do not change setup or start an investigation from this check. Ask for an explicit investigation request and one order reference before starting a workflow.", "For clients with public MCP or direct HTTP execution: call get_auth_guide, then request_sign_in_link with the owner's email and an optional business name. Tell the human to open the email, review the account action, and confirm to continue. Never read, redeem, or return the email token on their behalf. Account creation and OAuth approval remain pending until the human completes them. create_account is an optional legacy password path.", "For a custom MCP client, discover the issuer, register a public client (token_endpoint_auth_method: none), and use authorization_code with S256 PKCE, random state, and oauth_resource. Request openid and app.access for workspace reads; include offline_access if refresh is needed. Open authorization for the human's sign-in, workspace choice and consent, then exchange the callback code using the original code_verifier and redirect_uri. Store OAuth tokens in the client's credential store." ], "notes": [ "request_sign_in_link returns delivery acceptance, not an authenticated session or proof of an agent connection. Passwords are optional and can be set through the hosted password setup email flow. Public MCP password signup creates an account; it returns no password, session cookie, or access token. It does not authorize workspace access. Existing accounts should sign in instead of retrying signup.", "Direct HTTP endpoints are for clients that can execute requests and securely retain credentials; an ordinary web reader cannot POST to them. Preserve the exact signed oauth_query from each provider redirect. Sign-in, business selection and consent remain human steps; never manufacture consent or skip it.", "Signup/signin API responses contain session credentials: keep them private. Session tokens are not workspace OAuth access tokens.", "On RATE_LIMITED honor retry_after_seconds. On a network error after signup, try sign-in to check whether creation completed before retrying.", "WebMCP is an evolving browser API. We detect document.modelContext and support the earlier navigator.modelContext API; ordinary forms and public MCP remain available in other browsers." ] } ## First request (MCP 2026-07-28) POST https://auth.onticord.ai/mcp Content-Type: application/json Accept: application/json, text/event-stream MCP-Protocol-Version: 2026-07-28 Mcp-Method: tools/call Mcp-Name: get_auth_guide { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "get_auth_guide", "arguments": {}, "_meta": { "io.modelcontextprotocol/protocolVersion": "2026-07-28", "io.modelcontextprotocol/clientInfo": { "name": "your-agent", "version": "1.0.0" }, "io.modelcontextprotocol/clientCapabilities": {} } } } Use server/discover or tools/list with the same request metadata to discover the server or schemas. No initialize handshake or MCP session ID is needed for 2026-07-28. Older clients may initialize with 2025-11-25 and then call tools normally. GET /mcp returns 405; streaming happens on POST responses.