Permissions

The MCP Server does not have its own permission system. What your AI agent can access is determined entirely by the platform-level 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.

​

Token types and permission behavior

When you create a token — in the MCP Server page or through the Platform API — you choose between two scoping options. The choice determines how the token relates to platform permissions.

​

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 are full access tokens tied to the authenticating user.

​

Scoped tokens

A scoped token carries its own selection, chosen per resource type when you create it: which tables, which volumes, which secrets, which semantic-layer documents, which live connections, and which tools it may call. Each is independent — a token can name three tables and no secrets at all. That selection is not the last word. On every request it is narrowed to what the creating user can still access, so a scoped token can only ever be narrower than its creator:

• Access the creator loses is dropped from the token immediately. If their permission to trusted.customer_orders is revoked, the token stops seeing that table on its next call — no rotation, no editing.
• Access the creator gains is not added. The selection stays the selection. To widen a scoped token, edit it.

​

Scoping on Starter and Free

Choosing individual resources is part of the permissions model, and permissions are enforced on Growth and Custom only. On Starter and Free a scoped token therefore works one whole resource type at a time: for each kind of resource you choose all of it or none of it. The five are independent. A token with All tables and All secrets on and the rest off reaches every table and every secret, and no volumes whatsoever — off means none, not “inherit”. Turning all five on is still a scoped token, not a full access one.

​

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.

​

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. Every semantic-layer tool additionally requires a full access token. A scoped token is refused outright rather than silently treated as its creator.

​

Semantic layer permissions

The semantic layer — the context documents get_semantic_context reads — is organized into folders, each with its own access rules, and a token sees exactly what its user sees. Two consequences worth knowing when an agent comes back empty-handed:

• An empty get_semantic_context result is ambiguous. It can mean the question matched no document, or that the relevant documents are in folders this token’s user cannot read. Rephrasing fixes the first and never fixes the second, so the agent will say there may be documentation you don’t have access to instead of retrying.
• Creating a document needs a folder you can write to. A document created without one lands at the root of the semantic layer, which most users cannot write to. Agents call list_semantic_layer_folders(writable_only=True) first to choose a destination; an empty result there means the user cannot create documents anywhere and the agent should stop rather than retry.

​

Troubleshooting