# Build with AI

> Give AI tools the Prosaic docs, API and your books: llms.txt, Markdown pages, two MCP servers, the SDK skill and the manifest schema.

Source: https://developer.prosaic.works/docs/ai/build-with-ai

This site is written for language models as well as people. You can hand a model the docs as plain Markdown, connect it to an MCP server that searches the docs and the API, connect it to your own books, and give a coding agent a skill that knows how the SDK should be used.

Which to reach for:

- **Writing code against the API?** The developer MCP server and the SDK skill.
- **Building an extension?** The developer MCP server, then the CLI to deploy.
- **Working in your books from a chat — questions, reports, bookkeeping?** The data MCP server.

## Docs as Markdown

| URL                                                             | What it is                                                                                                                                                     |
| --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `https://developer.prosaic.works/llms.txt`                      | An index of every doc page with a one-line summary, following [llmstxt.org](https://llmstxt.org), plus links to the SDK, CLI, MCP servers and OpenAPI document |
| `https://developer.prosaic.works/llms-full.txt`                 | Every doc page in one Markdown file                                                                                                                            |
| `https://developer.prosaic.works/docs/{category}/llms-full.txt` | One section in one file — for example `/docs/ledger/llms-full.txt` or `/docs/extensions/llms-full.txt`                                                         |
| `https://developer.prosaic.works/docs/{category}/{slug}.md`     | One page as Markdown — add `.md` to any doc URL                                                                                                                |

The section names are `getting-started`, `ledger`, `sdk`, `apps`, `extensions` and `ai`. A prompt as short as this works with any model that can fetch a URL:

> Read https://developer.prosaic.works/llms.txt, then write a Node script that posts a balanced journal to a Prosaic entity using prosaic-node.

The API itself is described in the [API reference](/docs/api), which is also served as Markdown at `https://developer.prosaic.works/docs/api.md`, and as an [OpenAPI document](/openapi.json) if your tool imports specs.

## The developer MCP server

`prosaic-dev`, at `https://developer.prosaic.works/mcp`, is a read-only MCP server for building on Prosaic. It needs no sign-in and never touches anyone's books: it searches these docs, looks up API operations, and scaffolds and checks extensions.

| Tool                          | What it does                                                                                                                                                                                |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `search_docs`                 | Keyword search over these docs. Returns each match's page URL, Markdown URL and a snippet.                                                                                                  |
| `get_doc`                     | Returns one doc as Markdown, by `category` and `slug` or by its `url`.                                                                                                                      |
| `search_api`                  | Keyword search over the public API. Each result has its method, path and SDK call, such as `prosaic.journals.create(entityId, params)`.                                                     |
| `get_api_operation`           | One operation in full: parameters, request body schema, responses and the SDK call. Look it up by `operationId` (the SDK method name, such as `journals.create`) or by `method` and `path`. |
| `list_extension_scopes`       | Every scope an extension can declare, and what it grants.                                                                                                                                   |
| `list_extension_triggers`     | Every event with its input payload, the cron format, and the action-link placements.                                                                                                        |
| `scaffold_extension`          | The files for a new extension project, as a map of paths to contents.                                                                                                                       |
| `validate_extension_manifest` | Checks a `prosaic.extension.toml` with the same rules as the CLI.                                                                                                                           |
| `get_extension_reference`     | All the extension docs in one response.                                                                                                                                                     |

The API tools read the OpenAPI document published with the [Node SDK](/docs/sdk/node), so a result names the SDK method as well as the HTTP route. If that document can't be fetched, the tools say so and point at the API reference.

### Claude Code

```bash
claude mcp add --transport http prosaic-dev https://developer.prosaic.works/mcp
```

Add `--scope project` to share it with your team through the project's `.mcp.json`, or `--scope user` to have it in every project.

### Codex

```bash
codex mcp add prosaic-dev --url https://developer.prosaic.works/mcp
```

This writes the server to `~/.codex/config.toml`, which the Codex CLI, app and IDE extension share. You can add it there by hand instead:

```toml
[mcp_servers.prosaic-dev]
url = "https://developer.prosaic.works/mcp"
```

### Cursor

Open this install link, and Cursor asks you to confirm:

```text
cursor://anysphere.cursor-deeplink/mcp/install?name=prosaic-dev&config=eyJ1cmwiOiJodHRwczovL2RldmVsb3Blci5wcm9zYWljLndvcmtzL21jcCJ9
```

Or add it to `.cursor/mcp.json` in your project, or `~/.cursor/mcp.json` for every project:

```json
{
  "mcpServers": {
    "prosaic-dev": {
      "url": "https://developer.prosaic.works/mcp"
    }
  }
}
```

### VS Code

Open this install link, and VS Code asks you to confirm:

```text
vscode:mcp/install?%7B%22name%22%3A%22prosaic-dev%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fdeveloper.prosaic.works%2Fmcp%22%7D
```

Or add it to your user profile from a terminal:

```bash
code --add-mcp '{"name":"prosaic-dev","type":"http","url":"https://developer.prosaic.works/mcp"}'
```

Or add it to `.vscode/mcp.json` in your workspace:

```json
{
  "servers": {
    "prosaic-dev": {
      "type": "http",
      "url": "https://developer.prosaic.works/mcp"
    }
  }
}
```

### Gemini CLI

```bash
gemini mcp add --transport http prosaic-dev https://developer.prosaic.works/mcp
```

This adds it to the project's `.gemini/settings.json`. Add `--scope user` to put it in `~/.gemini/settings.json` for every project.

### Claude.ai and Claude Desktop

1. Open **Customize → Connectors**.
2. Click **+ Add**, then **Add custom connector**.
3. Name it `Prosaic developer docs`, enter `https://developer.prosaic.works/mcp` and click **Continue**.
4. Under **Authentication**, choose **No sign in**, then click **Add**.

On Team and Enterprise plans, an organisation owner adds connectors under **Organization settings → Connectors**: click **Add**, hover over **Custom** and choose **Web**. Members then connect it from **Customize → Connectors**.

### ChatGPT

1. In ChatGPT on the web, open [Plugins](https://chatgpt.com/plugins).
2. Click the plus button, then **Add custom MCP server**.
3. Name it `Prosaic developer docs`, and under **Connection** enter `https://developer.prosaic.works/mcp` as the **Server URL**.
4. Set authentication to **No authentication**.
5. Confirm the risk warning and choose **Create as a plugin**, then install the plugin to use it in a conversation.

## The data MCP server

`prosaic`, at `https://mcp.prosaic.works/mcp`, connects a model to your own books. It signs in with your Prosaic account over OAuth, then acts as you, with the role you hold in your workspace. Its tools cover entities and clients, contacts, bank transactions and reconciliation, journals, the ledger and general ledger, the chart of accounts, fixed assets, GST returns, invoices, financial reports, files and rules, plus the same extension tools as `prosaic-dev`.

Many of its tools write: they create journals, reconcile transactions and change accounts in real books. Most clients ask before each write; read what the model proposes before you approve it.

It's for accounting-firm accounts. People who reach Prosaic through a client portal can't use it.

There's nothing to configure beyond the URL. The client discovers Prosaic's sign-in, registers itself and opens your browser for you to sign in.

### Claude Code

```bash
claude mcp add --transport http prosaic https://mcp.prosaic.works/mcp
claude mcp login prosaic
```

`claude mcp login` opens your browser to sign in. You can sign in from a session instead: run `/mcp` and choose the server.

### Codex

```bash
codex mcp add prosaic --url https://mcp.prosaic.works/mcp
codex mcp login prosaic
```

Codex doesn't sign in when you add the server, so run `codex mcp login` before you use it. In `~/.codex/config.toml` the server is:

```toml
[mcp_servers.prosaic]
url = "https://mcp.prosaic.works/mcp"
```

### Cursor

Open this install link, and Cursor asks you to confirm:

```text
cursor://anysphere.cursor-deeplink/mcp/install?name=prosaic&config=eyJ1cmwiOiJodHRwczovL21jcC5wcm9zYWljLndvcmtzL21jcCJ9
```

Or use the `mcp.json` config for `prosaic-dev` above, named `prosaic` and with `https://mcp.prosaic.works/mcp` as its URL. Cursor runs the sign-in in your browser.

### VS Code

Open this install link, and VS Code asks you to confirm:

```text
vscode:mcp/install?%7B%22name%22%3A%22prosaic%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.prosaic.works%2Fmcp%22%7D
```

Or run:

```bash
code --add-mcp '{"name":"prosaic","type":"http","url":"https://mcp.prosaic.works/mcp"}'
```

VS Code opens your browser to sign in the first time it connects.

### Gemini CLI

```bash
gemini mcp add --transport http prosaic https://mcp.prosaic.works/mcp
```

Gemini CLI opens your browser to sign in the first time it connects. To sign in again, run `/mcp auth prosaic` in a session.

### Claude.ai and Claude Desktop

Follow the same steps as for `prosaic-dev`, with the URL `https://mcp.prosaic.works/mcp`. Keep the authentication settings Claude detects for it, which sign in with OAuth, and sign in to Prosaic when Claude asks.

### ChatGPT

Follow the same steps as for `prosaic-dev`, with the URL `https://mcp.prosaic.works/mcp` and authentication set to **OAuth**. ChatGPT asks you to confirm each write.

## The SDK skill for Claude Code

`prosaic-node` ships a [Claude Code skill](https://code.claude.com/docs/en/skills) at `skills/prosaic-sdk/SKILL.md`. It's a page of rules for an agent writing an integration, taken from how the SDK is meant to be used:

- Use the typed resource methods rather than inventing HTTP paths.
- Use an API key for your own server-side integration, and OAuth with PKCE for acting on someone else's behalf. Persist rotated refresh tokens atomically, and treat `invalid_grant` as "sign in again".
- Keep the `{ data }` envelopes, keep dates as strings, and use a decimal library for money.
- Never retry a financial write automatically after a connection error — the API has no idempotency keys, so check whether it happened first.
- Test against a local server or a stubbed `fetch`, never by writing to production.

To use it, [install the SDK](/docs/sdk/node), then copy the skill into your project:

```bash
mkdir -p .claude/skills
cp -R node_modules/prosaic-node/skills/prosaic-sdk .claude/skills/
```

Claude Code reads project skills from `.claude/skills/` and loads this one when a task matches its description: building an integration with the Prosaic SDK. Copy it to `~/.claude/skills/` instead to have it in every project. In other agents, add the file to the agent's rules or point the agent at it.

The package carries two more skills, `sdk-endpoints` and `sdk-release`. They're for maintaining the SDK itself, and you don't need them to build on it.

## Manifest schema for editors

Extension manifests have a JSON Schema at `https://developer.prosaic.works/schemas/extension-manifest.json`. Scaffolded manifests start with this line, which tells TOML editors where to find it:

```toml
#:schema https://developer.prosaic.works/schemas/extension-manifest.json
```

Editors built on [Taplo](https://taplo.tamasfe.dev/), such as the Even Better TOML extension for VS Code, then flag unknown scopes, event types and placements as you type. See the [Manifest reference](/docs/extensions/manifest#validation-in-your-editor).
