Atlas MCP Server

Overview#

Atlas can connect to outside AI tools in two directions, and this article covers both.

Inbound. Atlas publishes a Model Context Protocol (MCP) server. MCP is an open standard that lets an AI assistant call tools in another product. When you point an MCP-capable tool such as an AI coding assistant at Atlas, that tool can read your ontology, list your instance maps, inspect your libraries, and run Cypher queries against a compiled domain, all from its own chat window. When an administrator signs in through that tool, it can also build the model: create domains and libraries, define entity types, properties and relationships, edit instance maps, and compile.

Outbound. An Atlas agent can also act as an MCP client and call tools published by another product, such as the Timebase Historian. You would do this when you want an Atlas agent to reach data that does not live in Atlas. That direction is covered in Let an Atlas agent call another MCP server near the end of this article.

Two facts decide what inbound MCP gives you, so read them before you start:

• You must send a token. The /mcp endpoint requires a Pulse-issued bearer token on a default installation. A plain URL with no credentials is rejected.
• What you can do depends on whose token it is. A component token, the kind a service obtains with a client id and secret, gets the 37 read tools. A person who signs in through the AI tool with a Pulse account that holds the Administrator role gets 92 tools: the same reads plus every write, lifecycle and compile tool. The write tools are not hidden behind a setting; they appear or disappear per caller. See Sign in as a user for the write tools below.

The MCP endpoint#

Atlas publishes MCP on the same listener as the rest of Atlas. There is no extra service, no extra container, and no extra port.

Prefer the HTTPS address. Once you are sending a bearer token you should not send it over an unencrypted connection, and Atlas redirects plain HTTP traffic on 4551 to 4552 anyway. Note that the platform Compose file publishes only 4551, so if you are running the shipped compose file unchanged you need to publish 4552 yourself or terminate TLS in front of Atlas.

Transports#

Atlas uses the Streamable HTTP transport, which is what current MCP clients speak. Choose that option in your client and give it the /mcp address above.

For older clients that only speak the earlier HTTP-with-SSE transport, the MCP library Atlas uses also publishes two legacy paths automatically:

Do not point a Streamable HTTP client at /mcp/sse. It will fail to negotiate.

Before you begin: choose a credential#

Atlas ships with authentication switched on (Pulse:Auth:Enabled is true in settings.config). The /mcp endpoint is protected by the same rule as the rest of the Atlas API, so an anonymous connection is refused with 401 Unauthorized before your client can list a single tool. There are two ways to satisfy it.

Whichever you choose, two things must be true:

1. The token's audience must include Atlas. The audience (the aud value inside the token) says which product the token may be used against. It must contain the value of Atlas's Pulse:Auth:ClientId, which is Atlas by default. Pulse builds the audience from the client registration, so Atlas has to be in that client's audience list. A missing audience is the most common cause of a 401 from a token that looks valid.
2. The token travels over HTTPS as Authorization: Bearer <token>.

Connect with a component token (read tools)#

The steps are the same for every MCP client. Only the wording of the settings screen changes.

1. Obtain a Pulse bearer token with Atlas in its audience. Registering Timebase apps as OAuth clients in Pulse shows how to register a client and request a token.
2. Open your AI tool's MCP server settings.
3. Add a new server.
4. Set the transport to Streamable HTTP (some clients call this "HTTP" or "remote server").
5. Set the URL to https://<your-atlas-server>:4552/mcp.
6. Add a request header named Authorization with the value Bearer <YourPulseTokenHere>.
7. Save and reconnect. Your client should now list 37 Atlas tools.

Many clients store this as a small configuration file. The shape below is the common convention:

{
  "mcpServers": {
    "atlas": {
      "type": "http",
      "url": "https://<your-atlas-server>:4552/mcp",
      "headers": {
        "Authorization": "Bearer <YourPulseTokenHere>"
      }
    }
  }
}

A component token expires after an hour by default and the header does not renew itself, so this path suits scripts and short sessions. For day-to-day work, and for any write access, sign in instead.

Sign in as a user for the write tools#

Every write, lifecycle and compile tool on /mcp is gated by a policy that requires a token carrying the pulse:administrator role. Pulse puts that role on a token only when a person who holds it signs in; it never puts a role on a component token, however the client is configured. The gate is evaluated per request, so a caller without the role does not see the write tools in the tool list at all, and a call by name is refused.

To get the role to Atlas, your AI tool has to run the OAuth sign-in itself. Pulse does not support dynamic client registration, so the tool must let you supply a client id and secret you registered in advance, and it must use a fixed local callback port. Claude Code does both and is used as the example below; the Pulse side is the same for any client.

1. Register a client in Pulse#

In the Pulse web interface open Clients and create one client per person, for example claude-code-<name>, so a secret can be revoked without affecting anyone else. Fill in the Grant configuration section as follows.

Save, and copy the generated secret. Pulse shows it once; if you lose it, rotate it.

Nothing changes on your user account. The Administrator role you already hold is what the token carries.

2. Configure the AI tool#

With Claude Code, add the server from a terminal. The --client-secret flag takes no value; it reads the MCP_CLIENT_SECRET environment variable or prompts for the secret, and stores it in the tool's credential store rather than in a config file.

MCP_CLIENT_SECRET="<secret from Pulse>" claude mcp add -s user --transport http \
  --client-id "<client id>" --client-secret --callback-port 8765 \
  atlas https://<your-atlas-server>:4552/mcp

The -s user option is Claude Code's configuration scope, not an OAuth scope. The OAuth scopes go in the configuration file, ~/.claude.json, where the finished entry looks like this:

"atlas": {
  "type": "http",
  "url": "https://<your-atlas-server>:4552/mcp",
  "oauth": {
    "clientId": "<client id>",
    "callbackPort": 8765,
    "scopes": "openid profile offline_access"
  }
}

Do not also set an Authorization header on this entry. A static header switches the OAuth flow off.

For another MCP client, supply the same four values wherever its settings put them: client id, client secret, callback port and scopes. The client discovers Pulse on its own: an unauthenticated call to /mcp answers 401 with a WWW-Authenticate header that points at https://<your-atlas-server>:4552/.well-known/oauth-protected-resource, and that document names Pulse as the authorization server.

3. Sign in and check#

1. Start a new session of the AI tool so it reads the changed configuration.
2. Open its MCP server list, select the Atlas entry and choose Authenticate. A browser opens on the Pulse sign-in page.
3. Sign in with your own Pulse account. Pulse sends the browser back to localhost:<port>/callback and the tool completes the exchange.
4. Reconnect. The tool list should now hold 92 tools, including CreateDomain, DefineOntologyNodes, UpdateLibraryProperties, CompileDomain and DeleteDomain.

Everything the tool does from here is done in your name. Atlas resolves the signed-in principal on every call, so a change made this way is attributed to you in the domain's Git history exactly as if you had made it in the built-in assistant. The access token lasts one hour and renews silently from the refresh token while you keep using it. After seven days idle you sign in again.

What the tools can do#

Atlas publishes 37 tools to every authenticated caller and a further 55 to an administrator who signed in. The names still say "Nodes" where the Atlas API and web interface now say "entity types"; they mean the same thing.

Tools every caller gets#

Domains and queries

Ontology in a domain

Instance maps

Libraries

Skills, agents and diagnostics

An external tool can read every skill and agent definition on your Atlas host. It cannot run one: skills are instructions the AI tool follows with whatever tools it holds, so with a component token they are documentation, and with an administrator sign-in they can drive the write tools below.

Tools an administrator gets in addition#

These appear in the tool list only for a signed-in administrator. Each one takes the same arguments as the matching action in the Atlas web interface and returns a readable confirmation or a readable failure.

Domain lifecycle

Ontology in a domain

Each Define, Update and Remove tool takes a list, so one call can add several entity types at once.

Instance maps

Libraries

Things to ask for#

Once connected, ask in plain language. Your AI tool picks the tool for you.

"List all the domains in Atlas and tell me how many node types each one has."

"Run a Cypher query against the packaging-line domain to count all instances."

"List every node type in the cooling-system domain and show me which ones extend Equipment."

"Show me all the node types in the isa95-equipment library."

And, signed in as an administrator:

"Add a Compressor entity type to the utilities domain that extends Equipment, with a DischargePressure property of type TVQ, then compile the domain."

"Create a library called site-standards that imports isa95-equipment."

Which branch a call acts on#

Every tool, read or write, accepts an optional branch argument. Leave it out and the call acts on the branch the Atlas repository currently has checked out, which is what the web interface shows. Supply an existing branch name to target another branch; an unknown name is refused rather than defaulted. Atlas logs the resolved branch and where it came from on every call, so a change can always be traced to a branch.

Writes land on that branch as ordinary Atlas commits, attributed to the signed-in person. Use the web interface or the Atlas API to merge.

What MCP does not do#

It reaches no files and runs no commands. The built-in Atlas assistant has Bash, FileSystem and Script tools. None of them is exposed over MCP, by construction: /mcp serves a client with no session, so the per-session workspace confinement those tools rely on cannot apply.

It cannot give a component write access. There is no client setting, scope or audience that puts the Administrator role on a client_credentials token. If an automated process needs to change a model, it has to do so through the Atlas API with its own controls, or a person signs in.

A non-administrator sign-in gets the read tools only. The role comes from the user who signed in, not from the client registration. Granting someone the write tools means making them a Pulse administrator, which also grants the rest of what that role carries.

Let an Atlas agent call another MCP server#

The outbound direction works the other way round: an Atlas agent connects to somebody else's MCP server as a client and gains that server's tools. This is how you give an Atlas agent access to, for example, Timebase Historian data.

You configure it in the agent definition file. Agent definitions are .md files with a settings block at the top. Atlas ships some, and you can add your own to the Agent/agents/ folder inside the Atlas data directory. New files are picked up the next time Atlas restarts.

Declare a server#

Add an mcpServers list to the settings block, then reference it in the agent's tools list:

mcpServers:
  - name: timebase-historian
    transport: http
    endpoint: http://historian:4511/mcp
tools:
  - mcp:timebase-historian
  - LibraryToolProvider

• mcp:timebase-historian gives the agent every tool that server publishes.
• mcp:timebase-historian:SomeToolName gives it just one named tool.

Settings you can use#

A stdio server looks like this:

mcpServers:
  - name: everything
    transport: stdio
    command: npx
    args:
      - "-y"
      - "@modelcontextprotocol/server-everything"
    env:
      DEBUG: "1"

The global timeout default lives in the Pulse:Gage:Resilience:ToolCallTimeoutSeconds setting. A call that times out or fails never crashes the agent run: it comes back to the agent as readable text so the agent can try something else.

Use the Docker service name, never an IP address#

When the target MCP server runs in another container on the same Docker network, endpoint must use that container's Docker service name, for example http://historian:4511/mcp. Do not use a bridge IP address such as http://172.22.0.2:4511/mcp. Docker hands out those addresses dynamically, so they differ on every machine and change every time the network is recreated. A manifest with a hardcoded IP works once and then breaks silently.

Use localhost only when an agent is connecting back to Atlas's own /mcp endpoint on its own container's real port.

In the platform Compose file the Historian, Atlas, Connect and Bridge share one project and one network, so containers on it find each other by service name.

Troubleshooting#

Atlas writes a startup line reading MCP endpoint mapped at /mcp. If that line is missing from the Atlas logs, Atlas did not finish starting, and the problem is not MCP.