# Nerve Developer Documentation

Nerve is an AI Chief of Staff for founders, by NerveLabs Inc. Its MCP server and REST API bring your daily briefing, agent status, and action queue into Claude and other AI tools. On a plan with write access they can also add actions and contacts, and the MCP server can find time and create events on your calendar.

## Connect

### Claude, Claude Desktop, and Cowork

1. In Claude, go to Customize, then Connectors, click +, and choose Add custom connector. On a Claude Team or Enterprise plan, an owner adds it first under Organization settings, Connectors.
2. Enter `https://getnerve.ai/mcp` as the connector URL.
3. Sign in with your Nerve account. Claude runs the OAuth flow and refreshes the token.

### Claude Code

Add the server, then run `/mcp` in Claude Code and follow the sign-in steps in your browser:

```bash
claude mcp add --transport http nerve https://getnerve.ai/mcp
```

To use an API key instead, create one in Nerve under Settings, Developer (https://getnerve.ai/dashboard/account) and pass it as a header:

```bash
claude mcp add --transport http nerve https://getnerve.ai/mcp --header "Authorization: Bearer nrv_YOUR_KEY"
```

To share the setup with a project, put this in `.mcp.json` at the project root and set `NERVE_API_KEY` in your environment:

```json
{
  "mcpServers": {
    "nerve": {
      "type": "http",
      "url": "https://getnerve.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${NERVE_API_KEY}"
      }
    }
  }
}
```

## Access by plan

- **Lite**: Free. No MCP or API access.
- **Pro**: $29/mo. Read tools on the MCP server, and the read endpoints on the REST API.
- **Operator**: $79/mo. Read and write tools on the MCP server, and every REST endpoint listed here.
- Team plans: Starter has no MCP access, Growth gets the read tools, and Enterprise gets read and write tools. See https://getnerve.ai/teams

## MCP tools

Call `tools/list` for every tool your plan includes. Some of them:

| Tool | Plan | What it does |
| --- | --- | --- |
| `nerve_briefing` | Pro and up | Your current daily briefing: summary, priority actions, recommendations, and focus items. |
| `nerve_list_actions` | Pro and up | The actions waiting for your review, filterable by status, source, type, or lane. |
| `nerve_agent_status` | Pro and up | Health and last run time for each agent. |
| `nerve_add_action` | Operator | Add an action to your queue for review in Nerve. |
| `nerve_add_contact` | Operator | Create a contact in Nerve, or update the one that matches. |
| `nerve_find_time` | Operator | Find open time on your connected calendar for a task. |
| `nerve_calendar_create` | Operator | Create an event on your connected calendar. |

## Authentication

Send a Bearer token in the `Authorization` header: an OAuth 2.1 access token or a Nerve API key. Either one is capped to what your plan includes.

### OAuth 2.1

- `GET /.well-known/oauth-protected-resource`: Protected resource metadata (RFC 9728)
- `GET /.well-known/oauth-authorization-server`: Authorization server metadata (RFC 8414)
- `POST /oauth/register`: Dynamic client registration (RFC 7591)
- `GET /oauth/authorize`: Authorization, signing in with your Nerve account
- `POST /oauth/token`: Authorization code and refresh token grants
- PKCE: S256 code challenges are verified at the token endpoint
- Access tokens last 1 hour and refresh tokens 30 days
- Access tokens work on the REST endpoints below as well as `/mcp`

Scopes:

- `nerve:read`: The read tools, and the REST endpoints the read key scope reaches
- `nerve:write`: The read and write tools, and every REST endpoint listed here
- `nerve:admin`: Accepted, with the same access as nerve:write

### API keys

1. Create a key in Nerve under Settings, Developer: https://getnerve.ai/dashboard/account
2. Name it and pick its scopes. Your plan sets which scopes a key can hold.
3. Copy it when it appears. Keys start with `nrv_` and are shown once.
4. Pass it as `Authorization: Bearer nrv_YOUR_KEY`, and revoke it from the same page when you're done with it.

Key scopes:

- `read`: GET /api/mcp/briefing, GET /api/mcp/agents
- `briefing`: GET /api/mcp/briefing
- `agents`: GET /api/mcp/agents
- `admin`: Every endpoint listed here, writes included

## REST endpoints

| Method | Endpoint | Key scope | OAuth scope | Description |
| --- | --- | --- | --- | --- |
| GET | `/api/mcp/briefing` | `read` or `briefing` | `nerve:read` | Your latest briefing: summary, priority actions, recommendations, and focus items |
| GET | `/api/mcp/agents` | `read` or `agents` | `nerve:read` | Health, last run time, and summary for each agent |
| GET | `/api/mcp/actions` | `admin` | `nerve:write` | Your action queue, filterable by status, source, type, and lane |
| POST | `/api/mcp/actions` | `admin` | `nerve:write` | Add an action, or several at once as { actions: [...] } |
| POST | `/api/mcp/contacts` | `admin` | `nerve:write` | Create a contact, or update the one with the same email or name |

The `admin` key scope covers every endpoint. Full schemas: https://getnerve.ai/openapi.json

Key management takes your signed-in Nerve session, not a Bearer token. Settings, Developer calls it, and creating keys is limited to 10 an hour:

- `GET /api/mcp/keys`: List your keys and the scopes your plan allows
- `POST /api/mcp/keys`: Create a key with a name and scopes. The raw key comes back once
- `DELETE /api/mcp/keys?hash=<hash>`: Revoke a key

Responses from `/api/mcp/*` carry an `API-Version` header (currently `1.0.0`). A missing, invalid, or expired token gets a 401 with a JSON body (`error`, `message`, `docs_url`) and a `WWW-Authenticate` header.

## Machine-readable discovery

- OpenAPI 3.1 spec for the REST endpoints: https://getnerve.ai/openapi.json
- MCP server metadata: https://getnerve.ai/.well-known/mcp.json
- OAuth 2.1 server metadata: https://getnerve.ai/.well-known/oauth-authorization-server
- Agent card: https://getnerve.ai/.well-known/agent.json
- Agents index: https://getnerve.ai/.well-known/agents.json
- Product summary for LLMs: https://getnerve.ai/llms.txt
- Full product description for LLMs: https://getnerve.ai/llms-full.txt
- MCP endpoint: https://getnerve.ai/mcp

## Contact

- Email: patrick@getnerve.ai
- Docs: https://getnerve.ai/developers
- Terms: https://getnerve.ai/terms
- Privacy: https://getnerve.ai/privacy
- Security: https://getnerve.ai/.well-known/security.txt