---
title: Connect your AI assistant
description: Add one address to your assistant to find standards and misconceptions and write teaching instructions. Add a key to check replies and run agents.
updated: 2026-11-05
---

> All VIABLE docs, for people and their agents: https://developers.viablelab.org/llms.txt

# Connect your AI assistant

Ask the AI assistant you already use to find a standard, name the misconceptions that get in its way and write How the AI helps with you. It takes one address, with nothing to install and no key to get.

```text
https://api.viablelab.org/mcp
```

This is an [MCP](https://modelcontextprotocol.io) server. To have your AI build courses and agents in VIABLE as you, use [the CLI](/docs/project/cli) instead.

## Add the address

Claude Code:

```bash
claude mcp add --transport http viable https://api.viablelab.org/mcp
```

Codex CLI:

```bash
codex mcp add viable --url https://api.viablelab.org/mcp
```

Cursor, in `.cursor/mcp.json`:

```json
{ "mcpServers": { "viable": { "url": "https://api.viablelab.org/mcp" } } }
```

VS Code, in `.vscode/mcp.json`:

```json
{ "servers": { "viable": { "type": "http", "url": "https://api.viablelab.org/mcp" } } }
```

Another assistant that connects to MCP servers over HTTP takes the same address. Then ask it:

> Find the standard for adding fractions with unlike denominators and the misconceptions that get in its way. Then write teaching settings that ask first, and show me the instructions the AI would get.

## What it can do

With no key:

- **Find a standard.** Search K-12 standards by words or code, and read one with its learning components (`find_standards`, `get_standard`).
- **Find misconceptions.** Math misconceptions from Eedi's graph, with the skills they hinder (`find_misconceptions`).
- **Write teaching instructions.** Turn teaching settings into the instructions a reply step gets (`teaching_instructions`).
- **Search public goods.** The catalog of open datasets, benchmarks and tools for K-12 AI (`find_public_goods`).
- **Check a document.** An agent file, a course package or teaching settings, against VIABLE's formats (`validate_document`).
- **List components.** What the VIABLE Harness carries (`list_components`).

With a key:

- **Check a reply.** Review it with VETTING before a learner sees it (`check_reply`). The key needs **Model requests**.
- **Run your agents.** List your project's published agents and run one (`list_published_agents`, `run_published_agent`). The key needs **Run agents**.

Without a key, no tool calls a model. The standards come from [Learning Commons](/docs/resources/learning-commons) and the misconceptions from Eedi, both under CC BY 4.0: the results carry the attribution to keep.

A reply counts as checked only when `check_reply` says `passed`. Your assistant decides whether to call it: nothing makes it check a reply first.

## Add a key for the rest

::: steps
1. **Create a key.** In [Operate → API keys](/dashboard/keys), choose **Create key**. Under **Scopes**, keep **Model requests** (`model:request`) to check replies and **Run agents** (`agents:execute`) to run agents.
2. **Set its limits.** Give it a **Monthly cost (USD)** you're comfortable with. Your assistant decides how often to call these tools.
3. **Keep the secret out of the chat.** Store it as `VIABLE_API_KEY` where your assistant starts, and send it as a bearer token.
:::

Claude Code:

```bash
claude mcp add --transport http viable https://api.viablelab.org/mcp \
  --header "Authorization: Bearer $VIABLE_API_KEY"
```

Codex CLI:

```bash
codex mcp add viable --url https://api.viablelab.org/mcp --bearer-token-env-var VIABLE_API_KEY
```

Cursor, in `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "viable": {
      "url": "https://api.viablelab.org/mcp",
      "headers": { "Authorization": "Bearer ${env:VIABLE_API_KEY}" }
    }
  }
}
```

VS Code, in `.vscode/mcp.json`:

```json
{
  "servers": {
    "viable": {
      "type": "http",
      "url": "https://api.viablelab.org/mcp",
      "headers": { "Authorization": "Bearer ${input:viable-key}" }
    }
  },
  "inputs": [{ "id": "viable-key", "type": "promptString", "description": "VIABLE API key", "password": true }]
}
```

Model calls are billed to the key's project like any other call to the API, and the key's scopes, allowed models and limits apply. Each one appears in [Operate → Request logs](/dashboard/logs).

> [!NOTE]
> An assistant that only asks for an address can't send a key yet: it gets the tools that need none. Signing in with OAuth, for those assistants, is planned.

## Hosted or on your computer

The same tools also run on your own computer, as `viable-harness mcp` from the [VIABLE Harness](https://github.com/VIABLE-Learning-Lab/viable/blob/main/harness/docs/mcp.md). Choose by where your data should go.

| | Hosted | On your computer |
| --- | --- | --- |
| **Setting up** | An address | Node.js 22 and the VIABLE Harness |
| **What you send** | Goes to VIABLE | Stays on your computer, apart from what you send to your model endpoint |
| **Model calls** | VIABLE's, billed to your key | Your own endpoint and key |
| **Standards** | Yes, through VIABLE's access | No |
| **Misconceptions, public goods, teaching instructions, validation, components** | Yes | Yes |
| **Check a reply** | With a key | With your own endpoint |
| **Run an agent** | A published agent of your project | An agent file or course package you pass it |
| **Agent tests, the judge** | No | Yes |
| **Learners' records: measures, suggested changes** | No | Yes |
| **Without internet** | No | Yes, with a local model |

Choose local for learners' records, for your own model keys, or to work offline.

## What VIABLE keeps

- **Request logs keep no tool's arguments or results.** A log row holds the time, the status and how long it took, your address, your assistant's user agent and what Cloudflare reports about the connection, the request's headers with credentials removed, and the tool's name. With a key, also the key's prefix and project; for a call that used a model, its models, tokens and cost.
- **A run of your agent is kept like any other.** `run_published_agent` runs your agent the way the API does, so its message and reply are in the agent's **Test → Run history**. Send only what your project may keep.
- **Nothing else is kept.** The other tools hold what you send only for as long as the call takes. `check_reply` sends it to the reviewing model, and `find_standards` sends your words to Learning Commons, whose answers are cached for a day.

> [!WARNING]
> Never send a learner's name or email. Tools that take learners' records aren't on this server at all.

## Limits and errors

| What happens | What it means | What to do |
| --- | --- | --- |
| `429` from your address | One address may send 10,000 requests an hour to the API, with a key or without | Wait for `Retry-After` |
| `429` from your key | The key's **Requests per minute** | Wait for `Retry-After`, or raise the limit |
| `413` | Over 256 KiB without a key, or 1 MB of arguments with one | Send a smaller document, or use the local server |
| `401` | The key is wrong, revoked or expired. A bad key never falls back to no key | Fix the key, or remove it |
| `check_reply failed: it needs a VIABLE API key` | That tool needs a key | Add a key |
| `This API key doesn't have the … scope` | The key can't use that tool | Add the scope in [Operate → API keys](/dashboard/keys) |
| `Daily token limit exceeded`, `Account credit limit exceeded` | The key's limits or the account's credit | Raise the limit, or add credit or a provider key |

Where an assistant shows [MCP Apps](https://modelcontextprotocol.io/extensions/apps/overview), `check_reply`'s result also shows as a small page in the conversation: the outcome and each review round. Other assistants get the same result as text.

::: cards
- [Checking replies](/docs/build/vetting): what VETTING reviews, and how to add it to an agent.
- [How the AI helps](/docs/teach/ai-helps): what teaching settings do in an activity.
- [Standards, skills and misconceptions](/docs/teach/standards-and-skills): align an activity and listen for common mistakes.
- [Keys, credit and costs](/docs/project/keys-and-costs): give each key the scopes and limits you intend.
:::