> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nekt.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Permissions
> How platform permissions control what AI agents can see and do through the MCP Server.
The MCP Server does not have its own permission system. What your AI agent can access is determined entirely by the platform-level [permissions](/workspace/permissions) assigned to the user whose token is being used. If a user cannot see a layer on the platform, that layer will not appear in `list_layers`. If a table is inaccessible, `execute_sql` will return an error for queries against it.
The mapping is 1:1 — what the token's user sees in the platform is exactly what the AI agent can access through the MCP.
Data-level permissions are only enforced on **Growth or Custom plans**. On Starter, all members have Manager-level access to all data, so all tokens have full visibility.
## Token types and permission behavior
When you create a token in the [MCP Server](https://app.nekt.ai/mcp), you choose between two scoping options. The choice determines how the token relates to platform permissions.
| | **Full access token** | **Scoped token** |
| ---------------------------------------- | ------------------------------------------------------- | -------------------------------------------------------------------- |
| **Visibility** | Everything the creating user can access on the platform | A fixed list of tables selected at creation time |
| **Reflects platform permission changes** | Yes — automatically, without recreating the token | No — the scoped list is frozen at creation |
| **Best for** | Individual users connecting their own AI agent | Automation, integrations, or agents that need a stable, narrow scope |
### Full access tokens
A full access token inherits the permissions of the user who created it and stays in sync dynamically. If that user gains access to a new layer, the token immediately reflects it. If their access to a table is revoked, the token loses that access automatically — no token rotation needed.
Tokens created during the [OAuth flow](/mcp-server/authentication) are full access tokens tied to the authenticating user.
### Scoped tokens
A scoped token is restricted to the specific tables you select at creation time. That list is fixed: platform permission changes have no effect on what the token can see. To expand or restrict a scoped token's access, edit or recreate it.
A token can only be scoped to tables the creating user has access to at the time of creation.
## Practical examples
### Example 1: User receives Viewer access to an entire layer
**Scenario:** A member is granted Viewer access to the `raw` layer, which contains dozens of tables and several volumes.
**Action on the platform:** An admin grants Viewer access to the `raw` layer under **Workspace → Permissions**.
**What to expect in the MCP:**
* `list_layers` now includes the `raw` layer.
* `list_volumes` returns volumes inside `raw`.
* `list_tables` and `get_relevant_tables_ddl` include tables from `raw`.
* `generate_sql` and `execute_sql` can query those tables.
***
### Example 2: Table permission is revoked for a specific user
**Scenario:** A member previously had Viewer access to `trusted.customer_orders`. That permission is now revoked directly on the table.
**Action on the platform:** The permission is removed from the table — no group change is involved.
**What to expect in the MCP:**
* `execute_sql` returns an error for any query that references `trusted.customer_orders`.
* `get_table_preview` returns an error for that table.
* `get_relevant_tables_ddl` no longer returns its schema.
* `list_tables` no longer includes it.
***
### Example 3 (Troubleshooting): Group permission revoked — agent still has access
**Scenario:** An admin revokes the `raw` layer permission from a group. An AI agent using a full access token from a user in that group can still query tables in `raw`.
**Most likely causes:**
1. **Conflicting group permissions.** If the user belongs to another group — including the built-in **All** group — that still has access to `raw`, Nekt grants the highest permission the user holds from any assignment. Revoking access from one group alone does not remove access if another group retains it.
2. **Misconfigured change.** Verify the permission was saved correctly in **Workspace → Groups** or on the layer's Permissions tab.
Nekt always applies the **highest** permission a user has from any group or direct assignment. Revoking access in one group has no effect if another group (or a direct assignment) still grants it.
## How permissions apply to each tool
Most tools filter their output automatically to what the token can access. Tools that operate on resources outside the token's scope return an error rather than partial results.
| Tool | Permission behavior |
| --------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| `ask_about_nekt` | No data access — not affected by permissions |
| `list_layers` | Returns only layers the token can access |
| `list_volumes` | Returns only volumes in accessible layers |
| `list_files` | Returns only files in accessible volumes |
| `read_file` | Returns an error for files outside the token's scope |
| `list_tables` | Returns only accessible tables |
| `get_relevant_tables_ddl` | Semantic search is scoped to accessible tables only |
| `get_semantic_context` | No permission filtering — returns results regardless of token scope |
| `generate_sql` | Generates SQL using only accessible table schemas |
| `execute_sql` | Returns an error if the query references an inaccessible table |
| `get_table_preview` | Returns an error for inaccessible tables |
| `create_query` / `create_notebook` | Requires at least Editor access to the output layer |
| `run_pipeline` / `get_pipeline_status` | Requires access to the pipeline's input and output tables |
| `create_context_document` / `update_context_document` / `delete_context_document` | Admin only |
## Troubleshooting
The most common causes:
* **Group membership:** The token's user may belong to a group — including the built-in **All** group — that still has access to the resource. Check effective permissions in **Workspace → Members**.
* **Scoped token with a stale scope:** If you're using a scoped token, its table list was fixed at creation time. A table revoked on the platform may still be in the token's scope. Edit or recreate the token to remove it.
The most common causes:
* **Permission not yet assigned:** Verify the permission is set correctly in **Workspace → Permissions** or on the resource's own Permissions tab.
* **Scoped token missing the table:** If you're using a scoped token, the table may not have been included at creation time. Edit or recreate the token.
To confirm which type of token you're using, go to the [MCP Server](https://app.nekt.ai/mcp).