> For the complete documentation index, see [llms.txt](https://docs.corraldata.com/kb/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.corraldata.com/kb/mcp/authentication.md). # Authentication The CorralData MCP Server uses OAuth 2.0 for authentication. You sign in once through your organization's identity provider, and the server handles token management automatically. ## How authentication works When you connect to CorralData from Claude, ChatGPT, Claude Code, Codex, or any other MCP client, the following happens: 1. **Your assistant redirects you** to your organization's login page 2. **You sign in** with your existing CorralData credentials 3. **You grant permissions** for the assistant to access CorralData tools on your behalf 4. **The assistant receives a token** and uses it for all subsequent tool calls 5. **Tokens refresh automatically** — you won't need to sign in again unless your session expires ### Client ID and client secret Every MCP client identifies itself to CorralData with the public OAuth client ID `corral-mcp-client`. There is **no client secret**: the client is a public OAuth client protected by PKCE (Proof Key for Code Exchange), which is the standard for desktop tools and command-line clients that cannot keep a secret. If a setup form requires a client secret, enter any value; it is not checked. The client ID only tells CorralData which application is asking. Your own login is what decides what data you can see. ## Roles and permissions What you can do through your assistant depends on the roles assigned to your account in CorralData. | Role | Access level | | ------------------------ | --------------------------------------------------------------------------------------- | | **board.edit** | Create, update, duplicate, and reorder boards; create, update, and delete board filters | | **widget.edit** | Create and update widgets, Data Apps, and datasets, and validate widget queries | | **ai\_metadata.edit** | Set or update the customer's AI custom-instructions prompt | | *Any authenticated user* | All read-only tools: schema exploration, SQL execution, viewing boards/widgets/datasets | Roles are collected from **all companies** you belong to — if you have `board.edit` in any company, you can use board editing tools across CorralData. ### Tool-to-role mapping | Tools | Required role | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | | list\_boards, get\_board, list\_widgets, get\_widget, list\_board\_filters, get\_board\_filter, list\_datasets, list\_schemas, list\_tables, describe\_table, describe\_tables, get\_relationships, search\_tables, get\_query\_context, get\_column\_values, execute\_sql, lint\_sql, screenshot\_widget, list\_customers, list\_services, search\_service\_tools, call\_service\_tool (write actions require confirmation), list\_prompts, get\_prompt | *None (any authenticated user)* | | create\_board, duplicate\_board, update\_board, reorder\_board, create\_board\_filter, update\_board\_filter, delete\_board\_filter | board.edit | | create\_widget, update\_widget, bulk\_update\_widgets, validate\_widget\_query, create\_dataset, update\_dataset, create\_data\_app, update\_data\_app | widget.edit | | set\_customer\_prompt | ai\_metadata.edit | If you try an action you don't have permission for, your assistant will let you know. Contact your CorralData administrator to request additional roles. ## Security * Authentication uses the OAuth 2.0 Authorization Code flow with PKCE (S256), enforced for every login * The OAuth client is public by design: there is no shared secret to leak, and a client ID alone grants no access * All communication is encrypted over HTTPS * Tokens are validated server-side and have a limited lifetime * Signing out invalidates your session — no data is stored server-side --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.corraldata.com/kb/mcp/authentication.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.