Connect MCP

Hosted MCP at https://api.orishare.com/mcp (OAuth sign-in at https://api.orishare.com/mcp/connect) for Claude Code, ChatGPT, Cursor, Codex and any client: a small core that reaches every operation (search, describe, call), toolsets, acting as a customer, the production gate and pending approvals; signup tools with no credential.

Orishare runs an MCP server next to the API. It reaches every REST operation in openapi.json that an agent may call (all but a short, published hold-back list) through a small fixed set of tools, so it fits in a few KB of context and works in every MCP client, including clients without tool search. Anything a tool does is also a REST call.

Connecting your own AI app as a person? Add the connector URL https://api.orishare.com/mcp/connect to Claude, ChatGPT, Cursor, VS Code, Codex or any MCP client and sign in with OAuth, or use an AI access key. Step-by-step setup for each client is on Connect your AI. This page covers the server itself and agents that sign up on their own.

Hosted server

URL: https://api.orishare.com/mcp, streamable HTTP (POST /mcp).
Connector URL: https://api.orishare.com/mcp/connect, the same tools, for one-click sign-in. With no credential it answers 401 with a WWW-Authenticate header, which starts the OAuth sign-in in the client.
Credential: Authorization: Bearer <credential>, where the credential is the agent token from agent signup, a secret key (osk_test_... or osk_live_...), a personal access token or AI access key (opat_...), or an OAuth access token from a sign-in. Every kind works on both URLs.
A token (the agent token or any personal access token) also needs X-Orishare-Environment: env_... to name the environment it acts in. Start with the test environment id. A secret key is bound to one environment and needs no environment header, and neither does an AI access key or sign-in connection with a default environment.
OAuth: Orishare is an OAuth 2.1 authorization server for MCP clients. Discovery starts at GET /.well-known/oauth-protected-resource/mcp (or /.well-known/oauth-protected-resource/mcp/connect) on the API origin, which names the authorization server; the details for AI app developers are on Connect your AI.

Claude Code

claude mcp add --transport http orishare https://api.orishare.com/mcp \
  --header "Authorization: Bearer <agent token>" \
  --header "X-Orishare-Environment: <test environment id>"

With a secret key:

claude mcp add --transport http orishare https://api.orishare.com/mcp \
  --header "Authorization: Bearer osk_test_..."

Cursor, Windsurf and other clients (JSON)

Add this to the client's MCP configuration (.cursor/mcp.json, Windsurf's mcp_config.json, or the client's equivalent):

{
  "mcpServers": {
    "orishare": {
      "type": "http",
      "url": "https://api.orishare.com/mcp",
      "headers": {
        "Authorization": "Bearer <agent token>",
        "X-Orishare-Environment": "<test environment id>"
      }
    }
  }
}

Leave out X-Orishare-Environment when the bearer is a secret key. Some clients call the type streamable-http or infer it from url; the server and headers stay the same. Keep the file out of version control when it holds a credential, or read the value from an environment variable if your client supports it.

Connected with no Authorization header, the hosted server offers only two tools:

orishare_signup_start (no input): returns a single-use proof-of-work challenge, valid 10 minutes, with the instructions to solve it.
orishare_signup_complete: takes project_name, challenge and your nonce, plus the optional allowed_origins, owner_email, agent_name, timezone and retry_id. It creates the project and returns the same fields as POST /v1/agent/signups.

The hosted server never solves the proof of work for you. Run the Node or Python one-liner on Start here for AI agents; it takes about a second. Then store the secrets, give the claim link to your person, and reconnect the server with the agent token as Authorization: Bearer <token> and the test environment id as X-Orishare-Environment.

Local stdio server

The stdio server runs on your machine from the Orishare repository (apps/mcp, after pnpm install). With no credential it offers one tool, orishare_signup, which solves the proof of work locally and signs up in one step:

ORISHARE_API_URL=https://api.orishare.com/v1 node apps/mcp/bin/orishare-mcp.js

After signup, restart it with the agent token and the test environment:

claude mcp add orishare \
  -e ORISHARE_API_URL=https://api.orishare.com/v1 \
  -e ORISHARE_TOKEN=opat_... \
  -e ORISHARE_ENVIRONMENT=env_... \
  -e ORISHARE_DASHBOARD_URL=https://app.orishare.com \
  -- node /path/to/orishare-monorepo/apps/mcp/bin/orishare-mcp.js

With a secret key, set ORISHARE_API_KEY=osk_... instead of ORISHARE_TOKEN and ORISHARE_ENVIRONMENT.

The core: search, describe, call

An authenticated connection lists eleven tools (about 9 KB), whatever the size of the API:

Tool	What it does
`get_context`	Who you are, the organization, project and environment, the autonomy mode, plan usage, terminology
`search_actions`	Finds operations by what you want to do, in plain words; each hit says whether it changes data and whether it runs here
`describe_action`	The input schema (path, query, body), a recorded example, error codes and the live-environment policy of one operation
`call_action`	Runs any operation by id through the same pipeline as a direct API call
`list_topics`	The topics operations are grouped in, with counts
`enable_toolsets`	Adds whole topics as ordinary tools for this session
`switch_environment`	Acts in another environment for the rest of the session (tokens only)
`act_as_customer`	Mints a short-lived customer session for one end user
`create_change_set`	Proposes configuration changes with a plan; changes nothing yet
`create_change_set_application`	Applies a proposed change set under the environment's autonomy policy
`create_change_set_undo`	Proposes (and where allowed applies) the rollback of a committed change set

The loop for anything: search_actions { query: "award points to a customer" } gives ids such as post_ledger_entries; describe_action { id } shows its input; call_action { id, path, query, body } runs it. Errors come back with the API's code and a hint for the next step (for example validation_failed points back to describe_action). Writes take an optional idempotency_key or retry_id; the same one replays the first answer instead of acting twice. A large input (such as create_change_set) is summarized: pass variant (a command type like rule.create) or detail: "full".

Every operation listed in capabilities.json carries call_action: reachable, or held_back with its reason; gate_class for writes; runs_as_customer for the customer surface. Of 638 operations, 593 are reachable and 45 are held back:

Held back	Why
`staff_only`	The staff console's own routes
`auth_handshake`	Signup, invitation acceptance and the claim: a person's own step, or the signup tools
`end_user_link`	Signed unsubscribe and preference links a customer opens from an email
`inbound_callback`	Provider callbacks (Shopify, Klaviyo, email delivery events) signed by the provider
`dashboard_confirmation`	Confirming a change set, changing the autonomy policy, approving a pending action
`recursive_assistant`	The dashboard assistant's own conversations and turns
`others_secrets`	Answers holding a secret for someone else (an invitation token)
`non_json_transport`	Image bytes and the customer change stream

Toolsets

Clients that handle many tools (or defer them behind tool search) can turn topics into ordinary tools: enable_toolsets { enable: ["rules", "segments"] } for the session, "workflows" for the guided composites, "all" for everything. The answer carries notifications/tools/list_changed. Without a session, configure them on the connection with the header X-Orishare-Toolsets: rules,segments or ?toolsets=rules,segments in the URL (for clients such as ChatGPT connectors that only take a URL). A toolset lists all eligible ordinary tools of its topics: the operations your credential can call as a tool. Customer-surface operations (after act_as_customer) and operations your credential kind or scopes cannot call as a tool stay call_action-only; list_topics gives per topic actions (callable), tools (listed) and the reasons for the rest, with totals in coverage. Every operation id is also callable by name directly, listed or not. The default is no toolset: the core alone.

Sessions and environments

initialize answers with an Mcp-Session-Id. Clients send it back; the session remembers enabled toolsets and a switched environment for 24 hours of inactivity, bound to the credential that created it. switch_environment { environment: "production" } (or an id or a name) moves a token's session; a secret key stays bound to its own environment. Requests without the header stay stateless; DELETE /mcp with it ends the session.

Acting as a customer

Customer-surface operations (what a player or shopper does: their balances, quests, redemptions, teams) run as one end user, never implicitly. act_as_customer { customer_id } mints a customer session and returns a customer_session handle; pass it to call_action. An AI connection (one-click sign-in or AI access key) and an agent token pass no key at all: the session is minted with the keys the server holds for the selected environment, which the AI never sees. A secret-key connection uses itself; any other caller passes secret_key and publishable_key. The handle is sealed by the server: it cannot be read back into keys, works only for the connection that minted it, and expires with the customer session (at most an hour). The call is sent the way your app sends it: publishable key plus customer session.

The production gate for AI callers

Every data-changing call an AI makes is judged in a live environment by the environment's autonomy mode and the operation's class. An AI call is one made over MCP, by the dashboard assistant, or with an AI credential over plain REST: the agent token and the keys an agent created, the access token of an app connected with OAuth sign-in, and an AI access key. People in the dashboard and their own keys and tokens are not affected. A test environment always runs.

Class	`auto`	`limits`	`confirm`
`runtime`	runs	runs (one customer, under the rules and caps)	waits
`setup`	runs	runs (widget, assets, import uploads)	waits
`access`	runs	runs (origins, identity, connectors); credentials: see below	waits
`configuration`	runs	runs (drafts, copy, messaging, reports)	waits
`value_configuration`	runs	waits: trust, eligibility, reward delivery (use a change set)	waits
`value_grant`	runs	runs when the amount is read and within `max_award_per_grant`	waits
`destructive`	runs	waits (deletes, revocations, refunds, transfers, rotations)	waits
`organization`	waits	waits	waits

confirm holds every AI write, the agent's own included. In limits, access that changes no credential (allowed origins, identity connections, connectors, attribute definitions) runs for every AI caller; access that revokes, deletes, replaces or redirects (rotating a webhook signing secret, editing an identity connection, webhook endpoint or connector) is destructive and waits; access that creates a credential (an API key, a claim code, a webhook endpoint with its signing secret, a customer token) runs only for an agent's own credentials (an unclaimed project has no person to approve its launch) and never for an app connected with OAuth or an AI access key. An agent's secret key also makes the server-key value grants in limits, and keeps sending its game server's runtime traffic (events, customers, sessions) over plain REST in confirm; over MCP the same call waits like every other AI write.

A held call answers 403 confirmation_required with details.reason ai_gate, the refusal (confirm_mode, cost_unread, over_cap, destructive, access, organization), the class and, when one exists, the change_set_command that does the same through a change set. Then either:

propose it as a change set (create_change_set, then create_change_set_application), which shows a plan and can be undone; or
call it again with request_approval: true (and a note): it becomes a pending action. An owner or admin sees it under Needs review in the dashboard's notifications, reads the exact request, and approves or declines it. An approved request runs once, exactly as recorded, with the requester's own credential (checked again, never with more access) under the original call's idempotency key, through the same pipeline and audit; retrying the original call afterwards replays the approved answer. Read the outcome with get_pending_action (from any environment you may read; list_pending_actions with scope: organization lists them all), whose checks say whether it would fail if it ran now. Operations that answer with a credential (keys, tokens, secrets, claim codes) or take one as input (provider API keys) are never requestable, and the refusal's details.pending_action.allowed says so up front, judged on the request itself: events (post_events, one or a batch) are requestable when no event carries a customer_token and every event has its own id (a request with a token is refused, never stripped); a request that would already fail (a customer that does not exist yet) is refused with will_fail. Pending actions only ever act inside their own organization and expire after 72 hours.

search_actions and describe_action say beforehand whether a call runs here or waits.

Read, propose and apply

The generated per-operation tools keep their exposure, listed per operation in capabilities.json:

Exposure	What it does	Examples
`read`	Reads configuration, customers and events. Changes nothing	`get_autonomy_policy`, `get_change_set`, `discover_capabilities`
`propose`	Stores a change set with its plan. Changes nothing live	`create_change_set`, `create_playbook_preview`
`apply`	Applies a pending change set, or undoes a committed one, under the environment's autonomy policy	`create_change_set_application`, `create_change_set_undo`

No tool changes the autonomy policy or confirms a change set for a person.

The agent gate: credentials an agent created

Credentials an agent holds (the agent token, and any key the agent created with it) meet the production gate above on every transport, over MCP and over the REST API alike: the same classes, modes and refusals (details.reason ai_gate) as any AI caller, plus what the table's notes give an agent's own credentials. A held call names the path that works for that operation: details.change_set_command when a change-set command does the same, otherwise details.pending_action (request it with request_approval: true, or POST /v1/pending_actions). describe_action, search_actions and get_context (gates) say what an agent's call meets.

Value grants follow the caps: in limits, a manual ledger entry (POST /v1/ledger_entries) runs directly when its amount is positive and within max_award_per_grant; above the cap, negative or unreadable it waits (refusal over_cap, destructive or cost_unread).
Never an agent's to change: members, invitations, ownership, the organization, projects and the autonomy policy (403 forbidden, details.reason agent_not_permitted).

In a test environment an agent credential has its normal access. The gate stays after a claim until the owner replaces the agent's keys and token.

The local stdio server still serves the generated per-operation tool list (no core yet); prefer the hosted server.

On this page