# Connect this agent to the Onto MCP

Use these instructions to connect the current agent, then verify access without changing project data.

## Find the MCP endpoint

Use the setup guide URL from the user's message. The MCP endpoint is `/api/mcp`
on that same origin: keep the scheme, hostname and port, and replace the path
`/agent-setup/prompt.md` with `/api/mcp`. The guide URL itself is not the MCP endpoint.
Do not substitute a different host or assume production when the guide is on staging.

The connection uses normal OAuth organization selection. Do not add an organization
ID to the URL or infer one from browser tabs. The organization selected during
authorization determines access.

## Add the connection in this client

Prefer an available native MCP or plugin setup tool. Reuse an existing connection only when its full URL matches. Preserve other connections and settings; if the name `onto` is already used for a different URL, choose a distinct name and use it consistently below. Do not edit global agent instructions, `AGENTS.md`, or `CLAUDE.md`, or install extra packages.

For **Codex with terminal access**, use the installed CLI when native setup tools are unavailable. Replace `<MCP_URL>` with the MCP endpoint determined above using safe shell quoting:

```sh
codex mcp add onto --url '<MCP_URL>'
codex mcp login onto
```

For **Claude Code**, use the installed CLI to add a remote HTTP connection for this user:

```sh
claude mcp add --transport http --scope user onto '<MCP_URL>'
```

Then use `/mcp` in Claude Code to authenticate the Onto connection through OAuth. Do not use a local stdio server or install an MCP wrapper.

For **ChatGPT**, use native setup tools if available. Otherwise give the user these short steps: open **Plugins → + → Add custom MCP server**, name it **Onto MCP**, paste the full URL, choose **OAuth**, and create the plugin. If it is not installed yet, open the new plugin and select **+** to install it. Use the user's intended ChatGPT account and workspace.

For **another client**, use its native remote HTTP MCP connection settings and OAuth support. Consult that client's current official documentation if necessary. If you cannot perform setup directly, give the user only the steps that require their action; do not pretend to have configured it.

## Authorize and verify

Let the client open its normal OAuth sign-in and consent flow. The user signs in to Onto, selects the organization they want to use, and approves access. Do not automate the browser, inspect tabs, navigate to Onto settings, or handle the user's credentials yourself.

After authorization, check that `onto_start_session`, `onto_search` and `onto_execute` are available, including your client's tool search if tools are loaded on demand. Installing a connection or completing consent does not prove that this chat can use it.

If the connection is installed but any of these tools are missing, tell the user to **fully quit and restart the desktop app, reopen this chat, and ask you to verify the connection again**. For Codex desktop, explicitly say: **“Fully quit and restart Codex.”** Closing a window or starting another chat is not a substitute. Do not restart the app yourself. For a terminal client, ask the user to exit and relaunch the agent; for a browser-only client, reload the app and reopen the chat.

When the tools are available:

1. Call `onto_start_session` with no arguments.
2. Clearly tell the user **Connected to [organization name]**, using the organization returned by the tool, and follow the returned agent guide. If the user named a different organization, stop and reconnect through normal OAuth for that organization.
3. Call `onto_search` with `{"query":"onto_list_projects"}` to get the project-list operation schema. Then call `onto_execute` with `{"code":"async () => { return await onto.call(\"onto_list_projects\", {}); }"}` and report the verified organization and available projects. An empty list is a valid result.

Do not claim setup succeeded until these tool calls succeed. Do not create, modify, or delete project data during setup.

Use this search-and-execute workflow automatically for ordinary Onto requests. The user does not need to ask for Code Mode. Operation names returned by `onto_search` are called through `onto.call` inside `onto_execute`, not as standalone MCP tools. Use `onto_start_session` and the Story and Fact Log viewer tools directly as the session guide instructs; viewers must be called directly to display their cards.

Authentication and organization errors are separate from missing tools. For expired authorization, reconnect through the client's normal OAuth flow. For an organization mismatch, stop and reconnect with the organization the user requested. Do not silently use a different organization or repeat sign-in to work around an access-denied error; report the error.

## Official client references

- [Codex MCP setup and OAuth](https://learn.chatgpt.com/docs/extend/mcp?surface=cli)
- [ChatGPT custom MCP plugin setup](https://developers.openai.com/plugins/quickstart)
- [Claude Code remote MCP setup, scopes, and OAuth](https://code.claude.com/docs/en/mcp)
