# Sanka MCP

Connect an AI client to your hosted Sanka workspace with browser-based OAuth.

This guide explains how to connect an AI client to the hosted Sanka MCP server. The local `sanka` CLI is a separate tool for code migrations.

## Hosted workspace MCP

The hosted Sanka MCP server connects Claude Code, ChatGPT Codex, and other compatible AI clients to your Sanka workspace. It uses browser-based OAuth so each user signs in and approves access without placing a Developer API key in the client configuration.

Depending on the approved scopes and your Sanka permissions, an agent can:

- inspect business records such as companies, contacts, orders, and invoices
- create or update records when the authorized user has write permission
- review approval requests and workflow state
- preview an operation before carrying out a consequential change

## Hosted endpoint

Use the hosted endpoint:

```text
https://mcp.sanka.com/mcp
```

Do not add an API key, bearer token, or query parameter to this URL. The server starts the OAuth flow when the client connects.

## ChatGPT Codex: hosted connection

Add the server, then start OAuth sign-in:

```bash
codex mcp add sanka --url https://mcp.sanka.com/mcp
codex mcp login sanka
```

Complete Sanka sign-in and consent in the browser window. Use `codex mcp get sanka` to inspect the saved server configuration.

## Claude Code: hosted connection

Add the remote HTTP server:

```bash
claude mcp add --transport http sanka https://mcp.sanka.com/mcp
```

In Claude Code, run `/mcp`, select Sanka, and follow the browser sign-in flow.

## Generic MCP clients: hosted connection

For a client that supports remote HTTP servers and OAuth discovery, use:

```json
{
  "mcpServers": {
    "sanka": {
      "type": "http",
      "url": "https://mcp.sanka.com/mcp"
    }
  }
}
```

Field names can differ between clients, but the endpoint must remain `https://mcp.sanka.com/mcp`, and the client must support the hosted OAuth flow.

## Hosted permissions and safe operation

- Review the requested OAuth scopes and keep access to the minimum required.
- The connected user can act only within the Sanka permissions and workspace available to that user.
- Before a write, verify the selected workspace, target records, and proposed change.
- Use a human approval step for consequential or irreversible operations.
- Review Sanka activity logs for important agent-triggered changes.

## Troubleshooting

- **The browser does not open:** copy the authorization URL shown by the client and open it manually.
- **Authentication is stuck:** use the client's MCP settings to clear or reconnect Sanka, then run the sign-in flow again.
- **Permission denied:** confirm both the approved OAuth scopes and the user's Sanka permissions.
- **Wrong workspace:** reconnect or switch to the intended Sanka workspace before reading or writing data.
- **Connection fails:** confirm the client supports streamable HTTP and OAuth discovery for remote MCP servers.

## Related pages

- [Developer API overview](/docs/developers/)
- [Quickstart](/docs/developers/)
- [Authentication](/docs/developers/authentication/)
- [Node / Python SDK](/docs/developers/sdk-node/)
