> 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

## 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 the CorralData integration from Claude or ChatGPT, the following happens:

1. **Claude/ChatGPT redirects you** to your organization's login page
2. **You sign in** with your existing CorralData credentials
3. **You grant permissions** for Claude/ChatGPT to access CorralData tools on your behalf
4. **Claude/ChatGPT 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

### Roles and permissions

What you can do through Claude or ChatGPT depends on the roles assigned to your account in CorralData.

| Role                     | Access level                                                                            |
| ------------------------ | --------------------------------------------------------------------------------------- |
| **board.edit**           | Create, update, and delete boards and board filters                                     |
| **widget.edit**          | Create and update widgets, datasets, and validate widget queries                        |
| *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 | *None (any authenticated user)* |
| create\_board, update\_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                                                                                                                                                                      | widget.edit                     |

If you try an action you don't have permission for, Claude or ChatGPT will let you know. Contact your CorralData administrator to request additional roles.

### Security

* Authentication uses the OAuth 2.0 Authorization Code flow with PKCE for enhanced security
* 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=<question>&goal=<endgoal>
```

`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.