Connect Codex CLI to Semogram

Set up a Semogram workspace MCP connection, authenticate, verify evidence-backed reads, and manage access in Codex CLI.

The steps below follow the client’s documented MCP setup. This client connection has not yet been verified end to end against Semogram; complete the first-read checks below to verify your workspace access.

Install

Before you start

You need a Semogram account with access to the workspace and permission to read the records you intend to inspect. Connecting an assistant does not create a workspace, import data, or grant additional permissions.

In Semogram, open the workspace Settings and copy the URL from Connect an AI assistant. Use the copied UUID-based URL, not the workspace name, the homepage, or the sign-in URL. Its shape is:

https://platform.semogram.com/api/mcp/workspaces/<WORKSPACE_ID>

Replace every placeholder below with that copied URL. The URL identifies the workspace; it does not contain an API key. This guide uses OAuth sign-in.

Add the remote server

In your terminal, run:

codex mcp add semogram --url "<YOUR_WORKSPACE_MCP_URL>"
codex mcp get semogram

Check the saved URL before signing in. If you prefer editing configuration, add this table to ~/.codex/config.toml instead of running the add command:

[mcp_servers.semogram]
url = "<YOUR_WORKSPACE_MCP_URL>"

Preserve your other settings and avoid creating duplicate tables. Use a distinct server name if you want to retain connections to several workspaces. The entry is a remote HTTP connection, so it does not need a local process or an npx command.

Run:

codex mcp login semogram

Complete the browser sign-in and consent flow with an account that belongs to the chosen workspace. Return to your terminal when authentication finishes. Starting Codex with a provider account is separate from authorizing Semogram.

Run codex mcp list, then start or reopen your Codex session. Use /mcp in the CLI session to inspect the active connection. If a session started before you added the server, reopen it so it loads the configuration.

Make your first read

Start a conversation with this request:

Use the Semogram MCP connection. Discover my available capabilities, confirm the workspace name and ID, and list the projects I can access. Do not change anything.

The assistant should use discover_capabilities, workspace_get, and project_list. Check the returned workspace and choose the intended project. Project tools on a workspace connection require its projectId; workspace resources such as sources and uploads do not.

Then ask about a known record or published query:

Use Semogram to inspect the delivery query we published for this project. Explain its inputs and show the records and run references behind its result. If the query is missing, tell me rather than creating one.

Use your own query name. A successful connection does not mean that this example query exists or that an answer is correct. Compare the returned evidence with a record you recognize before expanding the task.

Manage the connection

Inspect the entry with codex mcp get semogram. To sign out, run codex mcp logout semogram. To remove the configuration, run codex mcp remove semogram. Removing the client entry does not delete Semogram workspace data. Recheck the endpoint and authenticate again when switching workspace connections.

FAQ

What permissions does the assistant have?

Your current Semogram membership and permissions determine the available tools. Some mutations require confirmation or a current member approval under the operation's policy. An assistant's approval prompt and Semogram's server-side approval requirements are separate checks.

For long-running work, keep the returned job or operation ID and check its status. Saving a draft is not the same as executing it. The records returned by Semogram are sent to the assistant provider; use a client and account approved for the data your organization permits it to receive.

Why is the connection failing?

What you see	What to check
Sign-in is requested again or `401 missing_token`	Authenticate again in the client. Verify that you are signing into Semogram, not only the assistant provider.
`404 workspace_not_found`	Copy the URL again and check workspace membership for the account used during sign-in. A name or slug cannot replace the UUID.
The assistant responds without using Semogram	Name the connection explicitly, check that it is enabled, and ask it to discover the available tools.
Expected tools or projects are absent	Check your Semogram membership and permissions. Reconnecting does not grant access.
`405` when opening the MCP URL	A browser sends GET; Semogram's MCP endpoint accepts POST. Verify through the client rather than judging the browser response.
`429`	Wait for the `Retry-After` interval. See workspace consumer API limits.

For API-key scopes, source-write restrictions, and the complete error list, use the MCP reference.

Where can I learn more?

Read MCP tools and permissions, or return to assistant setup. For client controls that vary by version, consult OpenAI MCP documentation.

Connect Codex CLI to Semogram

On this page