Connection, permissions and user experience

Problem

DataDescriber staff need their agents to help maintain the Platform's inventory without repeating every action manually in a browser. The company also wants to demonstrate “talk to your data”, letting customers ask useful questions about described information and receive understandable results. Customers can do this through their agent's chat without having Platform open.

Agents should use the user's existing permissions. Users should know which tenant and environment they are working in and whether a request succeeded or failed. Connecting an agent must not grant extra access.

An agent can use several authorized MCP connections. Each connection is tied to one tenant and environment. A prompt can tell the agent which connection to use, but prompts and tool arguments must not change the tenant or environment of that connection.

This first delivery establishes the connection and permission boundary with two harmless tools. It proves the foundation for later inventory and query work; it does not itself deliver either business outcome.

Actors and goals

• Internal MCP user: connect a client, establish the intended context and verify read or read/write access with harmless tools. Inventory workers and demo readers are the longer-term audiences for this foundation.
• Tenant administrator: choose whether the tenant permits MCP and which people can read or write through it without granting unrelated business permissions.

Expected outcomes

These outcomes describe what users should be able to achieve with MCP. They guide implementation and acceptance testing.

Scope and non-goals

Included changes

• Sign in through WorkOS from an MCP client.
• Keep each MCP connection tied to the intended tenant and environment.
• Turn MCP on or off for a tenant using feature flags in WorkOS.
• Provide two harmless tools: hello_read returns a greeting; hello_write confirms write permission without changing data.
• Enforce read and write permissions.
• Explain why access is denied, what the user can do next, and how to set up the connection.

Non-goals

• Tools for working with inventory data or running queries are later work, along with the shared command/query logic they need.
• The two test tools return fixed messages. They do not read inventory, change business data or create business events.
• No new Platform screens are included. Users connect through their MCP client and sign in through WorkOS; administrators use the existing WorkOS controls for tenant activation and user permissions.

Behavioral boundaries

• MCP is off for a tenant by default. An administrator can turn it on with a feature flag in WorkOS, but users still need their own MCP permissions.

• Turning MCP off does not block sign-in. After sign-in, the server checks the tenant setting and the user's permissions before allowing MCP requests.

• Users need MCP read permission (mcp:read) to use MCP. The hello_write tool also requires write permission (mcp:write).

  Note

  These two test tools only check MCP read and write permissions. Future tools must also check the permissions required by the operation:

  • Reading data requires mcp:read and the operation's usual permissions.
  • Creating, changing or deleting data requires both mcp:read and mcp:write, as well as the operation's usual permissions.

• Each connection is tied to one tenant and environment. Using another tenant or environment requires its own authorized connection. Tool arguments, references and identity headers cannot change which tenant or environment the server has verified for that connection.

• Each authorized MCP client can use the tools allowed by the user's MCP permissions. This delivery does not let users give one client read-only access while another has read and write access. The setup instructions must explain what access users give their client.

• The server only lists tools the user is allowed to use. It checks the tenant setting and the user's permissions again when a tool is called. Calling a tool directly does not bypass these checks, even if it is missing from the list.

• Tool replies and error messages must not expose credentials, protected information or information about other tenants.

• Removing a user's permissions, withdrawing a client's consent, letting authentication expire and turning MCP off for a tenant stop access in different ways.

• Before release, add documentation to the repository explaining how users can disconnect their client and how administrators can remove permissions or turn MCP off for a tenant. It must also explain when authentication expires and how long each change can take to stop access. Permission changes and turning MCP off may take effect after a delay, but that delay must have a documented maximum.

• The server may use a previous permission check only until that check expires. It must then check access again. If it cannot confirm access, it must deny further requests.

Initial interaction

1. Add the supplied tenant/environment URL as a Streamable HTTP connection, following the MCP client's setup instructions.
2. Sign in and approve the connection through WorkOS in the browser. Cancelling does not grant access; users can try again.
3. Ask the agent to use hello_read to check access in the intended tenant and environment.

Saving a connection does not sign the user in. Signing in does not grant permission to use the tools.

The server exposes two fixed demonstration tools:

Neither tool reads inventory data, mutates metadata or emits business events. These working names are also used in the response reference and mockups. Both are harmless demonstrations, while the second deliberately requires write permission.

Expired authentication and recovery

The client renews authentication directly with WorkOS when possible. If authentication expires and automatic renewal is unavailable, the user must re-authenticate through WorkOS in the browser. Existing valid consent is reused; the user does not need to set up the connection again. Re-authentication does not grant missing Platform permissions.

Cancelling leaves access unavailable, but the user can try signing in again. After successful sign-in, retry the tool to check that access works again. Whether the client retries automatically must be checked in that client. Missing permissions or disabled MCP require an administrator's help. A temporary service failure calls for retrying later.

User stories

Each story links to its acceptance criteria, defined below.

Shared acceptance conditions

Tenant isolation and credential checks in AC-3 apply across the stories.

Acceptance criteria

The criteria below define observable behavior and its verification. Applicable correctness, authorization, tenant-isolation and data-integrity controls require passing evidence before release.

Screens and states

See the interactive mockups for connection, tool use and error recovery.

Messages and recovery

These are proposed server-owned messages. Client-visible presentation is reviewed separately in the mockups and the real-client journey. A denial must not look like successful execution.