Skip to main content

Cowork: Using the Model Context Protocol (MCP) Server

Admin and user steps for connecting an AI client (e.g. Claude) to Encompass via the Cowork MCP server: Allow MCP Access, MCP Servers record, OAuth or bearer token, endpoint URL. Needs Encompass Cowork app; v26.07+.

B
Written by Bailey Naas-Thornton

Minimum Version Required: 26.07

Pre-Conditions

  • App Library: Encompass Cowork must be installed in your system.

  • MCP access permission: Each user who connects needs the Allow MCP Access permission on their role. Administrators set this on the Roles table and need AI Agent Admin and Permission Edit rights to configure the connection.

  • External AI client: You need a third-party AI client that supports MCP connections (such as Claude).

Steps

The Model Context Protocol (MCP) server securely connects an external AI client directly to your Encompass system. Each person connects as their own Encompass user, so the AI can read and change only what that user's roles and field-level permissions allow, and every change is written to the Encompass audit trail as an MCP-server change.

There are two ways to authenticate, and both run as the individual user:

  • OAuth 2.1 (recommended): the user signs in with their own Encompass account when connecting. Required for clients such as Claude that use a "custom connector" flow.

  • Personal bearer token: the user generates a private token from their Profile page and pastes it into the AI client.

One-time setup (administrator)

  1. Grant MCP access: On the Roles table, enable Allow MCP Access for the role(s) whose users should be able to connect. It is checked on every request, so removing it cuts off access immediately.

  2. Create the connector record: In the MCP Servers configuration table, add one record for the AI client you are connecting (for example, "Claude"). Encompass automatically generates an OAuth Client ID and OAuth Secret for it. A single record can serve many users, so you no longer create a separate record per person.

  3. Set the redirect (callback) URL: In the connector record, set Redirect URI to the callback your AI client uses. For Claude this is https://claude.ai/api/mcp/auth_callback. OAuth sign-in is rejected if it does not match.

  4. Share the connection details: Give the endpoint URL, and for OAuth the Client ID and Secret, to the users who will connect.

Connecting your AI client (each user)

  1. Add a custom connector: In your AI client, add a new MCP server using the Encompass endpoint URL, formatted as https://api.e8.co/mcp?EncompassID=<YourEncompassID.> Your EncompassID is shown in the lower-left menu of any page, just under your username. Always use api.e8.co, not your normal Encompass domain.

  2. Authenticate with OAuth (recommended): enter the Client ID and Secret from your administrator, then sign in with your own Encompass credentials when prompted. The AI then acts as you, with your permissions.

  3. Or use a personal bearer token: in Encompass, open your Profile and choose Get MCP Bearer Token. Copy the token (it is shown only once) and paste it into your AI client. Generating a new token immediately revokes the previous one.

  4. Start working: Once connected, the AI automatically discovers the available Encompass tools. Prompt it normally (for example, "Show me this month's open orders") and it runs the request in Encompass using your permissions.

Fields And Definitions

  • MCP Endpoint: The web address an external client uses to reach your database, including your EncompassID (https://api.e8.co/mcp?EncompassID=<id).> Always use api.e8.co.

  • Allow MCP Access: The role permission that controls who may connect over MCP. It is verified on every request; a user without it cannot authenticate or run any tool.

  • OAuth Client ID / Secret: Per-connector credentials generated on the MCP Servers record. They identify the AI client, not the person, and each user still signs in with their own Encompass account.

  • Redirect URI: The callback the AI client returns to after sign-in, registered on the connector record (for Claude, https://claude.ai/api/mcp/auth_callback). The value sent during sign-in must match it exactly.

  • Personal Bearer Token: A private token a user generates from their Profile (stored only as a hash and shown once) to connect as themselves without the OAuth flow.

  • Available MCP Tools: Encompass exposes a focused subset of its core tools. Read-only: TableStructure, TableSearch, TableView, and FieldAudit. Write/delete: TableAdd, TableEdit, TableCopy, and TableDelete.

  • Rate Limits: To protect system performance, MCP connections are governed by limits on requests per minute and processing seconds per minute.

Best Practices

  • Grant access deliberately: Enable Allow MCP Access only for roles that need it. Because the AI runs as the individual user, it is automatically limited to that person's existing permissions, with no shared service account to over-provision.

  • Prefer OAuth over static tokens: OAuth ties each connection to a real sign-in and supports automatic token refresh and revocation. Use a personal bearer token only when a client cannot use the custom-connector flow, and treat it like a password.

  • Protect and rotate credentials: Keep OAuth Secrets and personal tokens confidential. Regenerate a personal token, or the connector's secret, immediately if it may have been exposed; the change takes effect right away.

  • Audit trail tracking: Every add, edit, and delete the AI makes is recorded in the standard Encompass audit trail, attributed to the real user and tagged as an MCP-server change, so you can see exactly what was changed and by whom.

Did this answer your question?