Endpoint and authentication

Endpoint

URL: https://app.getcassis.com/mcp/
Transport: Stateless Streamable HTTP, with a transport per POST. GET and DELETE are refused. No stdio mode.
Auth: OAuth 2.1 for interactive clients, or a long-lived API key as a bearer token for non-interactive agents and scripts. Any Cassis account works, including a sample-demo signup.
Keys: Prefix sk-k6-, issued by any member from API keys in the account menu (admins: Settings → API keys), valid for up to a year, and optionally scoped to one project. A key acts as the person who created it, except a gateway key, which acts as the person its gateway names (see Gateway delegation). See API keys.

With OAuth, the client opens a browser, you sign in with your Cassis account, and the token is stored and refreshed automatically. Signing in with Google needs an address Google reports as verified; otherwise the sign-in ends with access_denied. If your account moves to another organization, the next token refresh asks you to reconnect. Deactivated accounts and accounts awaiting approval cannot refresh their connection.

Connecting a client

Any client that supports remote MCP servers over Streamable HTTP can connect. Add the endpoint above and use OAuth when the client supports it; the tabs below are examples for three common clients.

Settings, then Connectors, then Add custom connector. Paste the endpoint URL and sign in when the browser opens.

bash

claude mcp add --transport http cassis https://app.getcassis.com/mcp/

Or type /mcp inside Claude Code. For a project-scoped, secret-free config committed to the repository:

.mcp.json

{
"mcpServers": {
  "cassis": {
    "type": "http",
    "url": "https://app.getcassis.com/mcp/"
  }
}
}

Settings, then MCP, then Add new MCP server. Paste the endpoint URL, transport HTTP.

For a non-interactive agent, load CASSIS_API_KEY from the environment and configure the MCP client to send it as a bearer token. Use the client’s MCP handshake over POST; a plain GET request is not a connection test.

Gateway delegation

A company MCP gateway that serves many people with one key uses a gateway key, created by an organization admin. On every request, the gateway names the person behind the call:

http

Authorization: Bearer sk-k6-...
X-Cassis-User-Email: firstname.lastname@example.com
X-Cassis-User-Name: Firstname%20Lastname

X-Cassis-User-Email: Required on every tool call with a gateway key. Matched without regard to case. The call runs as that member, with their role, and their chats are their own.
X-Cassis-User-Name: Optional. Used only when Cassis creates the person on their first question. Header values are ASCII, so send the UTF-8 name percent-encoded (Alo%C3%BFs for Aloÿs, %20 for a space).

Send the headers per request, not once per connection: one connection serves everyone behind the gateway. The connection handshake and the tool list work without them.

A refusal comes back as a tool error, not as HTTP 401, so one refused person does not break the gateway for everyone else. Show its message to the person. Cassis refuses:

a tool call with a gateway key and no X-Cassis-User-Email;
X-Cassis-User-Email sent with any other credential;
a suspended member, a person awaiting approval, or a Cassis staff account;
an address with no account in the organization, when the organization has not claimed its email domain.

The tool surface

Eleven tools in five groups, ten for an API key scoped to one project, which is not offered list_projects. The server is read-heavy on purpose: it answers questions, records feedback on them, reports project status, reads the source schema, and triages detected issues. Beyond your own chats, its only write is update_issue_status.

Group	Tools	What for
Query	ask_question, submit_feedback	Ask about the data and get an answer, the SQL, and the results, then rate the conversation
Discovery	ping, list_projects	Confirm the server is reachable, and find the project to work with
Project state	get_project_status, get_source_schema	Read what is published, the git-sync state, and the schema beneath the context
Issue triage	list_issues, get_issue, get_issue_evidence, update_issue_status	Work the queue of problems detected from real conversations and failing evals
Evals	get_eval_run	Read an eval run’s status and per-case results

Every tool except ping and list_projects takes an optional project_id, the project’s UUID. With an API key scoped to one project, it defaults to that project and naming any other project returns an error. The server’s instructions to the client name the key’s project and say to omit project_id. With OAuth or an unscoped key, start with list_projects to find the project, and pass its id to every other tool; leaving it out returns an error.

There is no context tool

The server does not read or edit the context. An agent reads it as files in a checkout, changes it there, and opens a pull request, which is why agent-driven curation requires the git path.

To do this	Use
Read the current context	A repository checkout. `cassis context pull` materializes one
Change the context	Edit the files in the repository, then open a pull request. See the git-managed curation workflow
Validate a change	cassis context check, cassis context fmt
Test that a change works	cassis context test
Check for regressions	cassis eval run
Publish	Merge to the default branch. The connected GitHub App imports and publishes, or your configured CI job runs `cassis context upload`. Confirm the published version or commit

Client behavior matters. Surface the clarification questions when ask_question returns needs_input, reply with the user’s answers on the same chat_id, and never invent a reply. Preserve chat_id for follow-ups. For context work, use a repository checkout and the CLI. Stop at the pull request unless the repository owner explicitly authorizes the agent to merge after required checks pass. Asking questions over MCP does not require a local CLI install.

Error convention

Handle both a returned error field and MCP tool errors, including parameter validation and service failures. Expired or revoked credentials return HTTP 401: OAuth clients re-run the flow, and an API key has to be replaced. A gateway key whose creator is no longer an admin also returns 401. Refusing one person behind a gateway is a tool error instead (see Gateway delegation). Full limits are in Limits and errors.