# Intro to Nominal MCP

Connect your agent to Nominal, then build your workflow through prompts.

Illustrated Claude Code sessions on synthetic shaker data. The tool calls match the Nominal MCP server, and tool output is shortened. Click a collapsed tool call to expand it.

## Connect Your Agent

Connecting your agent requires a one-time setup.

**Claude Code**

**1.** Add the Nominal server:

```bash
claude mcp add nominal \
  --transport http \
  https://api.gov.nominal.io/mcp \
  --client-id nominal-mcp \
  --callback-port 54545
```

**2.** Run `/mcp` in Claude Code, select **nominal**, and choose **Authenticate**. Finish signing in in the browser that opens.

**3.** To try it, paste a workbook link and ask:

```text
List the tabs in this workbook and the channels I can plot.
```

**Codex**

**1.** In Codex, choose **Settings → Configuration → Open config.toml**, and add the Nominal server to `~/.codex/config.toml`. Keep the first two lines above every `[table]` header, and leave `54545` unquoted.

```toml
mcp_oauth_callback_port = 54545
mcp_oauth_callback_url = "http://localhost:54545/callback"

[mcp_servers.nominal]
url = "https://api.gov.nominal.io/mcp"

[mcp_servers.nominal.oauth]
client_id = "nominal-mcp"
```

**2.** Sign in from your terminal:

```bash
codex mcp login nominal --scopes mcp:tools
```

**3.** To try it, paste a workbook link and ask:

```text
List the tabs in this workbook and the channels I can plot.
```

Where is the Codex configuration?

![Codex Settings showing the Open config.toml button in the Configuration section](https://dev.nominal.io/quickstart/_images/codex-open-config-toml.png)

Open your user configuration from Codex Settings.

**Other clients**

Any MCP client that supports OAuth with PKCE can connect. Configure it with:

| Setting | Value |
| --- | --- |
| Server URL | `https://api.gov.nominal.io/mcp` |
| Transport | Streamable HTTP |
| Client ID | `nominal-mcp` |
| Flow | Authorization Code with PKCE (S256) |
| Callback | The loopback redirect your client uses, for example `http://localhost:54545/callback` |

Your client’s MCP documentation has its configuration format.

I’m implementing an MCP client

Send token-exchange parameters, including `resource`, `code`, and `code_verifier`, in the form-encoded request body, not the query string. PKCE with S256 is required.

What can my agent do?

**Find and inspect.** Search runs and resources, find checklists, and read a workbook’s tabs, panels, and channels.

**Edit workbooks.** Create a workbook for a run or asset. Add, rename, reorder, and remove tabs; add panels; change layout, axes, colors, markdown, and video settings.

**Shape the data.** Add runs and assets as inputs, align runs, and create or edit variables.

**Check runs.** Run a checklist on runs and read the results.

To inspect values, open the workbook in Nominal or use [SQL](https://dev.nominal.io/quickstart/quick/quick-sql.md). Nominal-managed and self-hosted deployments expose the same tools.

## Issues

Using a different Nominal host?

The examples use `api.gov.nominal.io`. If your organization uses a different host, replace it everywhere above.

To find it, click the **Settings** icon (a gear) at the bottom of Nominal’s sidebar, then **API keys**, and click **COPY URL** beside **API URL**. Replace the trailing `/api` with `/mcp`: `https://api.gov.nominal.io/api` becomes `https://api.gov.nominal.io/mcp`.

Running a self-hosted deployment?

Your administrator enables either OAuth or API keys on the MCP endpoint. Follow [MCP on a self-hosted deployment](https://dev.nominal.io/quickstart/mcp/quickstart-self-hosted.md).

## Next

An Example Session →

Add a tab, plot channels on separate axes, and derive a signal, one prompt at a time.

[An Example Session](https://dev.nominal.io/quickstart/mcp/example-session.md)

Troubleshooting →

Match the error you see to its fix.

[Troubleshooting](https://dev.nominal.io/quickstart/mcp/troubleshooting.md)