Möbius
Guides

Connect AI and manage credentials

Connect your own AI tool as yourself, give an AI system or pipeline a scoped credential, and control what those credentials can reach.

This guide covers two jobs: connecting your own AI tool so it works as you, and giving an AI system or pipeline a scoped credential of its own. For endpoint and tool details, see the MCP reference, the REST API reference and Security.

Choose the right door

Möbius has two door families. Pick by who the caller is acting as.

FamilyDoorsActs asCredentialWhere you get it
WorkspaceWorkspace API, Workspace MCPYou, with your role, or a workspace credential a steward or admin authorisedYour own sign-in (browser, CLI, or a connected AI tool), or a Management API tokenIntegrations → MCP Gateway → Connect my AI tool; Settings → Integrations → Management API tokens
DataData API (REST, GraphQL), Data MCPA machine, on a scoped credentialA Data API token, scoped to tables in one environmentSettings → Integrations → Data API tokens

A credential belongs to exactly one family, and the other family refuses it. A Data API token sent to a Workspace API endpoint or to the Workspace MCP gets 401 before its scopes are read. A Management API token sent to the Data API or Data MCP gets 401 too. A pipeline that loads data and triggers recertification needs two credentials, one from each family.

Mint a Data API token

  1. Open Settings → Integrations and choose Generate token on the Data API tokens card.
  2. Pick the Environment. A token covers one environment, and only environments you hold are offered. Changing it clears the tables you selected.
  3. Give it a Token label. If you leave it blank, Möbius generates one that starts with the environment name.
  4. Under Data plane — Table scopes, choose the tables and set read and/or write on each. The picker lists the tables you own in that environment. Every table must be in the token's environment; otherwise the mint is refused.
  5. Optional: under Data plane — Model scopes, pick each ML model the token may call for scoring. A table scope doesn't grant scoring on its own.
  6. Optional, admins only: under PII unmask grants, tick the personal-data columns this token should receive unmasked. Every unmasked read is audited.
  7. Choose Generate Token.

The Copy these tokens now panel shows the access token and the refresh token. The refresh token is shown only once. Put both in your secrets manager before you leave the page.

  • The access token lasts 60 minutes. Exchange the refresh token for a new pair before then (see Rotating access tokens).
  • Each exchange starts a new 30-day refresh window. A token that keeps refreshing stays live. One left idle for 30 days lapses, and you mint a new one.

Mint a Workspace API token

Use this when an external system needs to read the audit trail, list members, trigger certification, author definitions or tell Möbius that a pipeline has run.

  1. In Settings → Integrations, choose New management token on the Management API tokens card. You need at least the Steward role.
  2. Add a Token label and tick the Management scopes you need. Reading the audit log or members needs Admin. Triggering certifications, authoring definitions and signalling pipeline recertification or data loads need Steward. The server checks this whatever the form shows.
  3. Set the Environment fence. Fence a pipeline token to one environment so that a dev credential can't signal production. Choose All environments only for read tokens such as audit or members.
  4. Copy the tokens from the one-time panel, as above.

Rotate, edit and revoke credentials

Each token in Settings → Integrations shows a Data or Management badge, its environment, its scopes, and when it was created and last used.

  • Rotate. Every refresh issues a new access token and a new refresh token, and the previous access token stops working. Keep only the latest pair. If a refresh token that has already been used comes back, Möbius treats that as a leak and revokes the token. Mint a new one.
  • Edit scopes (Data API tokens only). Choose the pencil icon to replace the token's table set. Saving rotates the credentials and shows a new access and refresh pair. The environment can't be changed, so to move a token to another environment, mint a new one. A token labelled Env: All envs (legacy) can't be edited. Revoke it and mint one for a single environment.
  • Revoke. Choose the bin icon. The token is refused on its next call. You can revoke tokens you created, and admins can revoke any token in the workspace. Revoking a token is recorded in the audit trail.

Connect your own AI tool (Workspace MCP)

This connects Claude, Cursor or another MCP client to Möbius as you. The tool gets your current role, in one environment.

  1. Open Integrations → MCP Gateway and choose Connect my AI tool.
  2. Enter your Email and Password. Optionally, add a Client name such as "Claude Desktop — laptop" so you can tell this connection apart from others later. Choose Sign in and connect. This starts a separate session for the tool. Your browser session isn't affected.
  3. If you can work in more than one environment, pick one and choose Connect to this environment. The session stays in that environment. To work in another environment, connect again.
  4. Copy the AI client MCP config into your client's MCP settings. It looks like this:
{
  "mcpServers": {
    "mobius": {
      "url": "https://<your-mobius-url>/api/agent/tools",
      "headers": {
        "Authorization": "Bearer <session-credential>"
      }
    }
  }
}

The credential is shown once. The panel shows when the credential expires (15 minutes after sign-in) and when the session ends (7 days). A client that can refresh uses the Refresh token shown there to keep the same session and environment. After the session ends, connect again.

What the tool can do. It can do only what you can do yourself, in the pinned environment, and it never gets more than your role allows. Your workspace also limits this door in each environment, on Workspace → Environments:

  • MCP Data Control sets what the door may return: Limited (the default) or Full. See Workspace MCP.
  • AI mutation autonomy sets whether the tool may change anything. At Low (the default), installed AI tools may read but every change is refused. You make changes in the Möbius app instead. At Medium, routine changes run, and irreversible or high-impact ones still wait for your decision in the Möbius app. High works like Medium, and admins are also notified of each change.

Creating or changing credentials is never available through an AI tool. That always happens in Settings → Integrations. A workspace can also turn off the Workspace MCP as a tenant capability control. The tool's calls are then refused with a message saying so.

Disconnect. Open Settings → Integrations → Live sessions, find the connection by its client name and environment, and choose Revoke. The tool is refused on its next call.

Connect an external AI system (Data MCP)

Use this for an agent or AI service that should read certified data under its own credential, not under a person's credential.

  1. Mint a Data API token that covers only the tables the system needs, in the environment it should read from.
  2. Copy the gateway address from Integrations → MCP Gateway → Quick setup, then add Möbius as an MCP server in the system's configuration:
{
  "mcpServers": {
    "mobius": {
      "url": "https://<mcp-gateway-url>/v1/mcp",
      "headers": {
        "Authorization": "Bearer <data-api-access-token>"
      }
    }
  }
}
  1. Refresh the access token before its 60 minutes run out, and give the system the new one.

The system sees only certified tables within the token's scope and environment. The MCP reference lists the tools.

Read the governance envelope

Every governed response that carries table data includes a governance envelope: meta.governance on REST, the governance block on MCP, and the governance field on GraphQL. Read it before you act on the data.

FieldWhat it tells you
verdictThe answer in one word. SAFE means certified and fresh. ADVISORY means served, but read reasons first. NOT_SAFE means don't act on it.
certificationStatus, certifiedAtThe dataset's certification state and when that certification was granted
subject.environmentLabelThe environment the data came from
freshnessWhether the certification is older than the workspace's freshness window, and the window size in hours
pii.fieldsThe fields that were masked before the data left Möbius, which is what was withheld
reasonsPlain-language reasons whenever the verdict isn't SAFE

On MCP query_table results, a row that was served despite failing a check carries _governance_flag. Such rows are disclosed, never dropped silently. The GraphQL reference shows the full shape.

What refuses a request

These checks run on every call:

  • Wrong family, unknown or revoked credential: 401.
  • Outside the credential's scope: 403. Add the table to the token.
  • Different environment: a token for one environment is refused on a dataset in another environment (403).
  • Not certified: an uncertified dataset can't be reached through the Data API or Data MCP.
  • Workspace suspended: every credential in the workspace gets 401.

A dataset's contract can also name the kinds of consumer it is meant for: people, AI, automation or external systems. When it does, every governed read of that dataset is recorded in the audit trail, with the door it came through, the credential used and the declared consumer list, so it can be reviewed. Access itself is decided by the checks listed above: the credential's family, scope and environment, and the dataset's certification state.

Control where Möbius connects (network boundary)

The network boundary limits where Möbius may pull data from and send data to. It doesn't limit who can call the API. The credential and the rate limits do that.

  1. Open Workspace → Governance → Network boundary. Only admins can change it.
  2. In Ingress (URL ingest hosts, S3 source buckets) or Egress (webhook hosts, S3 export buckets, write-back connectors), choose Add rule.
  3. Pick the Surface, Allow or Deny, and the target: a host such as corp.com or *.corp.com, a bucket such as prod-exports-*, or a connector id.
  4. Before you save, read the preview. It lists recently used destinations that the change would newly block, or it warns that this is the first rule in this direction. It also names any surface it couldn't check.
  5. Choose Add rule to apply.

A direction with no rules allows everything. Once it has one rule, only the destinations it explicitly allows get through, and a deny always beats an allow. Removing the last rule restores allow-all. On Enclave deployments there's no outbound vendor path, so URL ingest and webhook rules aren't configurable there.

Rate limits

Each credential is limited to 1,000 requests a minute, 30,000 an hour and 300,000 a day. Calls with no valid credential are limited by IP address instead. An over-limit call gets 429 with Retry-After. The Data MCP returns a real HTTP 429, not a tool error. Back off for the time given in Retry-After and don't retry in a loop. See Rate limiting.

Sign in from the CLI

mb auth login                      # browser sign-in, stored in the "default" profile
mb auth login --profile staging    # keep a second workspace or environment side by side
mb auth set --token <cli-token> --base https://<your-mobius-url>   # scripts and CI
mb whoami                          # profile, user, workspace, role and environment scope

For mb auth set, create the token in Settings → General → CLI Access. It inherits your role and environment scope. In CI, you can set MOBIUS_TOKEN and MOBIUS_API_URL instead. See the CLI reference.

On this page