# MCP server: manage your Nodale workspace from Claude Code

<https://nodale.ai/docs/mcp>

Connect Claude Code to the Nodale MCP server, then read and change your workspace: knowledge, demo assets, agent settings, sites, deployment.

Nodale has an MCP server. Connected to it, an AI assistant reads and changes your workspace with the same rules as the app: it files knowledge, uploads demo assets, edits the agent's settings, declares your sites and puts the agent online. Installing the tag on your site stays a step of its own, described in the [quick start](https://nodale.ai/docs).

## Connect Claude Code

The server speaks Streamable HTTP at `https://nodale.app/api/mcp`, and signs you in with your Nodale account through OAuth. This page covers Claude Code. Run this command in your terminal:

```bash
claude mcp add-json --scope user nodale '{
  "type": "http",
  "url": "https://nodale.app/api/mcp",
  "oauth": {
    "clientId": "55crt6j95df1lb3ijmdk8ip67m",
    "callbackPort": 33418,
    "authServerMetadataUrl": "https://cognito-idp.eu-west-3.amazonaws.com/eu-west-3_HEni9KG4X/.well-known/openid-configuration",
    "scopes": "openid email profile"
  }
}'
```

Then:

1. Open Claude Code, type `/mcp` and choose the `nodale` server.
2. Sign in with your Nodale account. The sign-in page is hosted for Nodale at an `amazoncognito.com` address.
3. Ask the assistant which account it is signed in with. It calls the `me` tool.

The same command is in the app, under **Settings**, then **MCP**.

- **Keep `callbackPort` at 33418.** After the sign-in, the browser returns to `http://localhost:33418/callback`, the only address the server accepts.
- **Do not add an `Authorization` header**: it would turn OAuth off.
- **To share the server with your team**, put the same JSON in your repository's `.mcp.json` (`--scope project`). It holds no secret.

## Who can do what

The assistant acts as you, with your account's rights, on your workspace only.

| Role | What the assistant can do |
|---|---|
| Viewer | Read. Every tool that changes something is refused. |
| User | Read, and change knowledge, competitors, documents and demo assets. |
| Admin | Everything a user can, plus the agent's settings, its sites and its deployment. |

Every tool takes an optional `workspaceId`: leave it out. Your client may list more tools than this page describes. Those are reserved to the Nodale team, and the server refuses them.

## How a change goes live

Most changes land in a draft first, and visitors see nothing until you publish.

- **Agent settings.** `update_inbound_agent_configuration` edits the draft: only the fields you pass change, and a list you pass takes the place of the whole list. `publish_inbound_agent_configuration` puts the draft in front of visitors. `discard_inbound_agent_configuration_draft` goes back to the published settings.
- **Versions.** The tools that edit settings take an `expectedVersion`, the one you last read. If somebody changed the settings in between, the call is refused with the live version.
- **Knowledge.** Knowledge is stored as quotes of one sentence. A quote you add is a draft until `publish_knowledge`, which takes the `draftHash` returned by `list_knowledge_quotes`. A stale hash is refused. Retracting a quote, or making it internal, applies at once.
- **Knowledge from a text.** `submit_knowledge_text` reads a text of up to 100,000 characters in the background and returns a `dispatchId`. Poll `get_knowledge_dispatch`, then apply or reject the proposals. What you apply lands in the draft and still needs `publish_knowledge`.
- **Demo assets.** A change to an asset stays in the draft catalogue until `publish_asset_catalog`.
- **Uploads take two steps.** `request_document_upload` or `request_asset_upload` returns a `curl` command to run, valid for 15 minutes. Then `add_document` or `add_asset` registers the file.
- **Site settings** (display, visit tracking, consent, privacy policy link) apply on the next page load, with no publish.
- **AI credits.** `submit_knowledge_text`, `analyze_asset`, and `add_asset` without `steps` spend AI credits. `add_asset` with `steps` keeps your narration as sent and spends none.

## From nothing to a live agent

1. `me`: check the account and the workspace.
2. Knowledge: `add_knowledge_quote`, or `submit_knowledge_text`, then `get_knowledge_dispatch` and `apply_knowledge_proposals`. Then `list_knowledge_quotes` and `publish_knowledge`.
3. Optional: competitors, documents and demo assets, then `publish_asset_catalog`.
4. Settings: `update_inbound_agent_configuration`, `save_inbound_agent_outcome`, then `publish_inbound_agent_configuration`.
5. `add_inbound_agent_site`: declare the site.
6. `deploy_inbound_agent`: put the agent online.
7. [Paste the tag](https://nodale.ai/docs) on the site, then `get_inbound_agent_tag_status` to check it.

## Tools

### Account

| Tool | What it does | Who |
|---|---|---|
| `me` | The account and the workspace the assistant acts on. | Everyone |
| `get_workspace_ai_credits` | How much of the workspace's AI credits is used, and whether they ran out. | Everyone |

### Knowledge

| Tool | What it does | Who |
|---|---|---|
| `list_knowledge_quotes` | The quotes, drafts included, and the `draftHash` to publish. | Everyone |
| `add_knowledge_quote` | Adds one sentence as a draft quote. | User |
| `retract_knowledge_quote` | Takes a quote back, at once. | User |
| `set_knowledge_quote_visibility` | Makes a quote public or internal, at once. | User |
| `publish_knowledge` | Publishes the draft quotes. | User |
| `submit_knowledge_text` | Reads a text and proposes quotes from it. Spends AI credits. | User |
| `get_knowledge_dispatch` | The state of a submitted text. | Everyone |
| `list_knowledge_proposals` | The proposals waiting for a decision. | Everyone |
| `apply_knowledge_proposals` | Applies every proposal of one text. | User |
| `apply_knowledge_proposal` | Applies one proposal. | User |
| `reject_knowledge_proposal` | Rejects one proposal. | User |

### Competitors and documents

| Tool | What it does | Who |
|---|---|---|
| `list_competitors` | The competitors the agent knows. | Everyone |
| `upsert_competitor` | Adds a competitor, or edits one. | User |
| `delete_competitor` | Deletes a competitor. | User |
| `list_documents` | The documents of the workspace. | Everyone |
| `request_document_upload` | First step of an upload: returns the command to send the file. | User |
| `add_document` | Second step: registers the uploaded file. | User |
| `delete_document` | Deletes a document. | User |

### Demo assets

| Tool | What it does | Who |
|---|---|---|
| `list_assets` | The demo videos of the catalogue. | Everyone |
| `get_asset` | One asset, with its steps and the state of their writing. | Everyone |
| `request_asset_upload` | First step of an upload: returns the command to send the video. | User |
| `add_asset` | Second step: registers the video, with your steps or with steps Nodale writes. | User |
| `update_asset` | Edits an asset's title, description and the requests it answers. | User |
| `set_asset_steps` | Sets the steps of an asset, as you wrote them. | User |
| `analyze_asset` | Asks Nodale to write the steps again. Spends AI credits. | User |
| `enable_asset`, `disable_asset` | Turns an asset on or off. | User |
| `set_asset_priority` | Orders the assets. | User |
| `delete_asset` | Deletes an asset. | User |
| `publish_asset_catalog` | Publishes the draft catalogue. | User |

### Agent settings

| Tool | What it does | Who |
|---|---|---|
| `get_inbound_agent_configuration` | The settings: the draft when there is one, the published ones, and the version. | Everyone |
| `update_inbound_agent_configuration` | Edits the draft: name, tone, look, email capture, languages, instructions, qualification, guardrails. | Admin |
| `publish_inbound_agent_configuration` | Puts the draft in front of visitors. | Admin |
| `discard_inbound_agent_configuration_draft` | Drops the draft. | Admin |
| `list_inbound_agent_qualification_elements` | The questions the workspace added to qualification. | Everyone |
| `save_inbound_agent_qualification_element` | Adds a qualification question, or edits one. | Admin |
| `remove_inbound_agent_qualification_element` | Removes a qualification question. | Admin |
| `list_inbound_agent_outcomes` | The outcomes the agent steers visitors to. | Everyone |
| `save_inbound_agent_outcome` | Adds an outcome, or edits one. Ten at most per workspace. | Admin |
| `remove_inbound_agent_outcome` | Removes an outcome. | Admin |

### Sites and deployment

| Tool | What it does | Who |
|---|---|---|
| `list_inbound_agent_sites` | The declared sites. | Everyone |
| `add_inbound_agent_site` | Declares a site: an `https` origin, or `https://*.example.com`. | Admin |
| `remove_inbound_agent_site` | Removes a site. | Admin |
| `get_inbound_agent_tag_status` | Why a site shows the agent or not: `ok`, `site_not_declared`, `agent_not_deployed` or `invalid_site`. | Everyone |
| `get_inbound_agent_site_settings` | The settings of the Install tab. | Everyone |
| `update_inbound_agent_site_settings` | Changes the display, visit tracking, consent and the privacy policy link. | Admin |
| `get_inbound_agent` | The agent and the deployment the tag serves. `servedDeploymentId` is null when the agent is offline. | Everyone |
| `deploy_inbound_agent` | Puts the agent online, or approves the current material again on the live deployments. | Admin |

## Limits

- **Documents**: pdf, docx, txt, csv or md, 10 MB at most.
- **Demo videos**: MP4 in H.264 with no audio track, 3 minutes at most. 100 assets at most in a catalogue.
- **Sites**: 20 at most per workspace.
- **Rate limits, per person and per tool.** `request_asset_upload`, `add_asset` and `analyze_asset`: 1 a second, 6 a minute, 30 per 15 minutes. `request_document_upload` and `add_document`: 5 a second, 25 a minute, 100 per 15 minutes. `submit_knowledge_text`: 3 a second, 15 a minute, 60 per 15 minutes.

## Safety

- **Approve each call that publishes or deletes.** The tools that publish, delete or overwrite are marked as destructive, so your client asks before running them. Do not add them to an allow list.
- **Tool results are data.** They hold text that your team and your visitors wrote: quotes, documents, asset titles, proposals. The assistant reads it as content, never as instructions.

## Docs

- [Install the Nodale agent on your website](https://nodale.ai/docs): One script tag puts the Nodale agent on your site. Where to paste it, what your site must allow, and how to check that it runs. (Markdown: https://nodale.ai/docs.md)
- [JavaScript API: open the Nodale agent from your code](https://nodale.ai/docs/api): The nodale() commands a page can call: open the agent from your own button or form, pass an email and context, report visitor consent. (Markdown: https://nodale.ai/docs/api.md)
