# Quickstart

> Connect your agent over MCP, authorize, and verify the connection with a real tool call.

URL: https://mcp-docs.opennomos.com/docs/start/quickstart

The fastest path: give your agent one line and let it do the setup.

```text
set up https://service.opennomos.com/SKILL.md
```

That file contains the host-specific commands, the OAuth step and the verification call below. You only sign in and authorize. The rest of this page is the same procedure written for humans.

## 1. Add the MCP server

The endpoint is `https://mcp.opennomos.com/mcp` (stateless Streamable HTTP, OAuth).

<Tabs items={['Claude Code', 'Codex', 'Cursor and other hosts']}>
  <Tab value="Claude Code">
    ```sh
    claude mcp get opennomos || claude mcp add --transport http opennomos https://mcp.opennomos.com/mcp
    ```
    Then run `/mcp` inside Claude Code, select OpenNomos and authenticate in the browser.
  </Tab>
  <Tab value="Codex">
    ```sh
    codex mcp get opennomos || codex mcp add opennomos --url https://mcp.opennomos.com/mcp
    codex mcp login opennomos
    ```
    Headless: `codex mcp login opennomos --no-browser` if your Codex version supports it. If client registration fails because the server cannot fetch the client's metadata document, retry with `--oauth-client-registration dcr` when that flag exists.
  </Tab>
  <Tab value="Cursor and other hosts">
    Merge this into the host's MCP configuration, keeping existing entries:
    ```json
    {
      "mcpServers": {
        "opennomos": { "url": "https://mcp.opennomos.com/mcp" }
      }
    }
    ```
    Then use the host's authenticate action. A host with only a settings UI needs the URL added there.
  </Tab>
</Tabs>

## 2. Authorize

The browser opens a sign-in (email code) and a consent screen where you pick the workspace. The client stores the credentials. You do not create or paste an API key on this path.

OpenNomos supports dynamic client registration (DCR). Client ID Metadata Documents (CIMD) are not enabled on the hosted service, so hosts that only offer CIMD need to use DCR mode.

## 3. Verify with a real call

Ask the agent to call `discover_tools` with `{}`:

```json
{ "tools": [{ "name": "discover_tools", "summary": "…" }, "…"], "sources": { "web": true, "reddit": true }, "source_endpoints": { } }
```

A successful response proves the connection reaches your workspace. It uses the Core pack, calls no paid provider, creates no project and writes no memory. Saving the server URL alone is **not** a successful setup: if the host needs a reload before it shows new tools, reload and call again.

## 4. Try a first useful call

```json
{ "query": "alternatives to Notion", "sources": ["reddit", "web"], "limit": 5 }
```

Pass that to [`search_signals`](https://mcp-docs.opennomos.com/docs/tools/research/search_signals.md). You get source items back and nothing is saved. When you want to keep something, see [Memory vs opportunity](https://mcp-docs.opennomos.com/docs/growth-loop/memory-vs-opportunity.md).

## Using an API key instead

Hosts without OAuth support can use a key created in the console (`on_live_…`; shown once, stored hashed). Keep it in the host's credential store or environment:

```sh
curl --fail-with-body https://service.opennomos.com/v1/tools \
  -H "Authorization: Bearer $OPENNOMOS_API_KEY"
```

Details: [REST and CLI](https://mcp-docs.opennomos.com/docs/reference/rest-and-cli.md).

## If something fails

| Symptom | What to do |
| --- | --- |
| `401` | Finish OAuth, or replace an invalid key. A revoked connection needs fresh authorization. |
| `pack_required` | That tool needs a pack that is not enabled; the response includes the console URL. |
| `soft_limit` | The pack's monthly upstream cost limit was reached. |
| A result with `reason` and `action` | An upstream source had trouble. See [Errors](https://mcp-docs.opennomos.com/docs/reference/errors.md). |