# NEXUS AI Quick Start for Agents

This page gets an AI agent from zero to a working NEXUS AI connection. Pick MCP for conversational agents, or the REST API for scripts and CI.

## Option 1: MCP (recommended for agents)

The MCP server is at `https://mcp.nexusai.run/mcp` (streamable HTTP). It exposes 74 tools.

Claude Code:

```bash
claude mcp add --transport http nexus-ai https://mcp.nexusai.run/mcp
```

Claude Desktop, in `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "nexus-ai": { "type": "http", "url": "https://mcp.nexusai.run/mcp" }
  }
}
```

Cursor: Settings, MCP, Add server, with the same URL. ChatGPT and other clients that support remote MCP servers use the same URL.

Sign-in uses OAuth 2.0 with PKCE and dynamic client registration. The client opens a browser on first connect and the user approves the requested scopes. Headless clients run the same flow once and send the access token as `Authorization: Bearer <token>`.

Personal access tokens (`nxk_...`) are for the REST API, not for MCP.

## Option 2: REST API

1. Create an access token in the dashboard at https://nexusai.run/settings/tokens, or with `nexus token create`. See [Access tokens](/docs/tokens.md).
2. Call the API with `Authorization: Bearer nxk_...`.

```bash
curl -H "Authorization: Bearer $NEXUSAI_TOKEN" https://mcp.nexusai.run/api/gpt/deployments
```

The schemas are in [OpenAPI](/openapi.json).

## First tasks

- Confirm identity: `nexusai_whoami`.
- List what exists: `nexusai_projects_list`, `nexusai_deploy_list`, `nexusai_managed_db_list`.
- Deploy a repository: `nexusai_deploy_source` with `repoUrl`, then poll `nexusai_deploy_status`.
- Read logs when something fails: `nexusai_deploy_logs`.

## Rules for agents

- Ask the user before any tool marked `destructive` in the [tool catalog](/mcp/tools.json).
- Request the narrowest scopes the task needs.
- Never paste secrets, tokens, or connection strings into chat, code, or logs.

## Related resources

- [Authentication](/docs/auth.md)
- [MCP](/docs/mcp.md)
- [Plans and limits](/docs/plans.md)
- [Errors and rate limits](/docs/errors.md)