> ## Documentation Index
> Fetch the complete documentation index at: https://docs.opennous.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> One call into the Nous context graph, for Claude Code, Cursor, Codex, Hermes, and any MCP client.

The Nous MCP server gives your agent the context graph as a focused set of tools, engineered and sourced context ready to act on. Have your agent call `get_workspace_status` first. It can set up the workspace itself.

## Fastest setup

One command installs the CLI, signs you in, and registers the MCP with your agent.

```bash theme={null}
curl -fsSL https://api.opennous.cloud/install | sh
```

Then tell your agent **"set up my Nous workspace"**. It finds your ICP, or drafts one from your website, and syncs it. That is onboarding.

Prefer to run it yourself.

```bash theme={null}
npx @opennous/cli init
```

`init` signs you in through the browser, saves a workspace key to `~/.nous/config.json`, and registers the server with your agent.

## Connect any client

Run `npx @opennous/cli login` once. It saves your key to `~/.nous/config.json`, so no key goes in your config. Then add Nous to your client.

```json theme={null}
{
  "mcpServers": {
    "nous": { "command": "npx", "args": ["-y", "@opennous/mcp"] }
  }
}
```

| Client             | Where to add it                                                                                                                      |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| **Claude Code**    | `claude mcp add nous -- npx -y @opennous/mcp`                                                                                        |
| **Cursor**         | `~/.cursor/mcp.json`                                                                                                                 |
| **Claude Desktop** | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS). `%APPDATA%\Claude\claude_desktop_config.json` (Windows)   |
| **Codex**          | `~/.codex/config.toml`. TOML, shown below                                                                                            |
| **Hermes**         | MCP settings. Set the name to `nous`, then paste the inner object `{ "command": "npx", "args": ["-y", "@opennous/mcp"], "env": {} }` |
| **Any MCP client** | its `mcpServers` block                                                                                                               |

```toml theme={null}
# Codex. ~/.codex/config.toml
[mcp_servers.nous]
command = "npx"
args = ["-y", "@opennous/mcp"]
```

<Note>
  No API key is needed once you have run `login`. The server reads your key from `~/.nous/config.json`. To pin a specific key instead, add `"env": { "NOUS_API_KEY": "..." }` with a key from **Settings → API Keys**.
</Note>

## Hosted server (remote HTTP)

For clients that cannot run a local process, like n8n cloud. Create an API key at **Settings → API Keys**, then add Nous with the URL and a Bearer token.

```json theme={null}
{
  "mcpServers": {
    "nous": {
      "url": "https://mcp.opennous.cloud/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}
```

* **n8n cloud**. MCP Client Tool node, Transport `HTTP Streamable`, Endpoint `https://mcp.opennous.cloud/mcp`, Auth `Bearer`.
* **Claude Code**. `claude mcp add --transport http nous https://mcp.opennous.cloud/mcp --header "Authorization: Bearer YOUR_API_KEY"`
* **Hermes**. In MCP settings set the name to `nous`, then paste the inner object `{ "url": "https://mcp.opennous.cloud/mcp", "headers": { "Authorization": "Bearer YOUR_API_KEY" } }`.

## The tools

### Daily

Read context, record what happened, keep notes, check what to work next.

<CardGroup cols={2}>
  <Card title="get_context" href="/mcp/tools/get-context" icon="brain">
    Engineered context for a task about one entity. The headline call before outreach or a meeting.
  </Card>

  <Card title="get_account" href="/mcp/tools/get-account" icon="user">
    The full account, every claim with epistemics plus the recent timeline.
  </Card>

  <Card title="query" href="/mcp/tools/query" icon="magnifying-glass">
    Retrieve and summarise activity across many people.
  </Card>

  <Card title="attention" href="/mcp/tools/attention" icon="bell">
    What needs attention. Accounts gone quiet, facts decayed.
  </Card>

  <Card title="get_action_items" href="/mcp/tools/get-action-items" icon="list-check">
    Open action items and commitments, grouped by account. What you owe them and what they owe you.
  </Card>

  <Card title="record" href="/mcp/tools/record" icon="pen">
    Record what happened. You observe, Nous derives the claims.
  </Card>

  <Card title="save_note" href="/mcp/tools/save-note" icon="note-sticky">
    Keep a meeting brief, transcript, or note on a contact's record.
  </Card>

  <Card title="search_notes" href="/mcp/tools/search-notes" icon="file-magnifying-glass">
    Semantic search across saved notes and documents.
  </Card>

  <Card title="get_playbook" href="/mcp/tools/get-playbook" icon="book">
    Read the user's rules (voice, outreach, icp, positioning) before you act.
  </Card>

  <Card title="verify" href="/mcp/tools/verify" icon="circle-check">
    Re-check a specific fact before you act on it. The calibration check.
  </Card>
</CardGroup>

### Setup

The agent sets the workspace up itself. Call `get_workspace_status` first. It returns a ranked next-steps list.

<CardGroup cols={2}>
  <Card title="get_workspace_status" href="/mcp/tools/get-workspace-status" icon="gauge">
    The whole setup state plus ranked next steps. The first call in a session.
  </Card>

  <Card title="set_workspace_profile" href="/mcp/tools/set-workspace-profile" icon="id-card">
    Agent-driven onboarding. Set name, website, business type, and ICP.
  </Card>

  <Card title="build_icp_model" href="/mcp/tools/build-icp-model" icon="sliders">
    Build the ICP scoring model from the synced GTM context.
  </Card>

  <Card title="train_icp_model" href="/mcp/tools/train-icp-model" icon="trophy">
    Train the ICP model on real closed-won and closed-lost deals.
  </Card>

  <Card title="sync_icp" href="/mcp/tools/sync-icp" icon="file-import">
    Sync the user's ICP and context files into the graph (file to graph).
  </Card>

  <Card title="export_icp_model" href="/mcp/tools/export-icp-model" icon="file-export">
    Get the learned ICP model to write back into the ICP file (graph to file).
  </Card>

  <Card title="sync_playbook" href="/mcp/tools/sync-playbook" icon="rotate">
    Push an edited playbook file into Nous so every agent obeys the same rules.
  </Card>

  <Card title="connect_integration" href="/mcp/tools/connect-integration" icon="plug">
    Connect a key-based integration (Apollo, Prospeo, HubSpot token, and more).
  </Card>

  <Card title="set_trigger" href="/mcp/tools/set-trigger" icon="bolt">
    Create an outbound event trigger (webhook).
  </Card>

  <Card title="list_triggers" href="/mcp/tools/list-triggers" icon="list">
    List the workspace's triggers plus the catalog of available events.
  </Card>
</CardGroup>

<Note>**Nous Cloud only.** `set_trigger` and `list_triggers`. On a self-hosted instance, Lead Lists, CRM Sync, Triggers, and Reports are Cloud-only. Everything else, including the ICP scoring model, is open.</Note>

## The daily loop

1. **Start a task.** Call `get_context` with the right `intent` for a ranked, budget-fit context block.
2. **Need the user's rules.** Call `get_playbook` (voice, outreach, icp, positioning). Never use `query` or `get_account` for this.
3. **Something happened.** `record` it. Nous derives the claims.
4. **Made something durable.** `save_note` the brief or transcript onto the contact.
5. **End of session.** Call `attention` for what to work next.

<Note>**`record` versus `save_note`.** `record` logs that something *happened* (an email, a meeting) and Nous derives claims from it. `save_note` keeps the *document itself* (a brief, a transcript), append-only and dated. Use both.</Note>

## Environment

| Variable       | Required                 | Default                      | Purpose                                      |
| -------------- | ------------------------ | ---------------------------- | -------------------------------------------- |
| `NOUS_API_KEY` | if not signed in via CLI | none                         | Workspace key. Create at Settings, API Keys. |
| `NOUS_API_URL` | no                       | `https://api.opennous.cloud` | Override for self-hosted.                    |

Source lives at [`apps/mcp`](https://github.com/NousC/opennous/tree/main/apps/mcp). Each release ships to npm as `@opennous/mcp@<semver>`. Pin a version for reproducible installs with `npx -y @opennous/mcp@0.43.0`.