Onboarded MCP Server

# Onboarded MCP Server An MCP (Model Context Protocol) server that enables AI assistants like Warp to interact with the Onboarded platform. It provides: - **API Discovery** — Automatically fetch and search OpenAPI specs to find available operations - **API Execution** — Execute any Onboarded API operation with automatic authentication - **Entity Memory** — Persist created entity IDs locally so the agent can reference them later - **Source Code Access** — Optionally read files from your local Onboarded repository Credentials are stored securely in macOS Keychain and shared with [onboarded-cli](https://github.com/OnboardedInc/Onboarded-CLI) — tokens never appear in MCP tool calls or responses. ## Setup ### Prerequisites - **Node.js 18+** - **git** - **onboarded-cli** — [github.com/OnboardedInc/Onboarded-CLI](https://github.com/OnboardedInc/Onboarded-CLI) ### Quick Setup (Recommended) The `onboarded` CLI handles everything automatically: ```bash onboarded mcp setup ``` This interactive command will: 1. Ask where to install (default: `./onboarded-mcp` in the current directory) 2. Clone this repository 3. Run `npm install` and `npm run build` 4. Add the server to Warp's MCP config (`~/.warp/mcp.json`) 5. Optionally configure the Onboarded repo path for `repo_read` tool After setup completes: 1. Restart Warp to load the MCP server 2. Authenticate: `onboarded auth login <profile-name>` ### Manual Setup If you prefer to set up manually: ```bash # Clone and build git clone https://github.com/OnboardedInc/onboarded-mcp.git /ABSOLUTE/PATH/TO/onboarded-mcp cd /ABSOLUTE/PATH/TO/onboarded-mcp npm install npm run build ``` Add to `~/.warp/mcp.json`: ```json { "mcpServers": { "onboarded": { "command": "node", "args": ["/ABSOLUTE/PATH/TO/onboarded-mcp/dist/index.js"] } } } ``` Optionally create `~/.config/onboarded-mcp/config.json` for `repo_read` tool: ```json { "onboardedRepoPath": "/ABSOLUTE/PATH/TO/onboarded" } ``` ## Available Tools ### Discovery Tools | Tool | Description | |------|-------------| | `spec_sync` | Fetch and cache OpenAPI specs from Onboarded APIs | | `ops_search` | Search for API operations by keyword | | `ops_describe` | Get detailed parameter and schema info for an operation | ### Execution Tools | Tool | Description | |------|-------------| | `api_call` | Execute any API operation by operationId | | `auth_status` | Check if credentials exist for a profile | ### State Tools | Tool | Description | |------|-------------| | `state_put` | Store an entity reference (ID, name, type) | | `state_query` | Query stored entities with filters | | `state_get` | Get a stored entity by internal or external ID | | `state_delete` | Remove an entity from local storage | ### Repository Tools (optional) Requires `onboardedRepoPath` to be configured. | Tool | Description | |------|-------------| | `repo_read` | Read a file from the local Onboarded repository | | `repo_list` | List files in a directory | ## Tool Reference ### spec_sync Fetch and cache an OpenAPI spec. - `api` (required): `"v1"` or `"internal"` - `env`: `"prod"` or `"staging"` (default: `"prod"`) - `source`: `"url"` or `"cache"` (default: `"url"`) ### ops_search Search for API operations by keyword. - `api` (required): `"v1"` or `"internal"` - `query` (required): Search term (matches operationId, summary, tags, path) - `topK`: Max results (default: 10) ### ops_describe Get detailed schema for an operation. - `api` (required): `"v1"` or `"internal"` - `operationId` (required): The operation to describe ### api_call Execute an API operation. - `api` (required): `"v1"` or `"internal"` - `operationId` (required): The operation to call - `params`: Path and query parameters as object - `body`: Request body for POST/PUT/PATCH - `profile`: Auth profile name (default: `"default"`) - `dryRun`: If `true`, return the request without executing ### auth_status Check authentication status. - `profile`: Profile name (default: `"default"`) ### state_put Store an entity reference. - `entityType` (required): e.g., `"employee"`, `"company"` - `api` (required): `"v1"` or `"internal"` - `externalId`: ID from the Onboarded API - `name`: Human-readable name - `data`: Additional JSON data - `env`: `"prod"` or `"staging"` (default: `"prod"`) ### state_query Query stored entities. - `entityType`: Filter by type - `api`: Filter by API - `env`: Filter by environment - `nameContains`: Filter by name substring - `limit`: Max results (default: 100) - `offset`: Pagination offset ### state_get Get a stored entity. - `id`: Internal UUID, or - `externalId` + `api` + `env`: Look up by Onboarded API ID ### state_delete Delete a stored entity. - `id` (required): Internal UUID ### repo_read Read a file from the configured repository. - `path` (required): Relative path (e.g., `"src/models/employee.py"`) - `startLine`: Start line number (1-indexed) - `endLine`: End line number (1-indexed) ### repo_list List files in a directory. - `path`: Relative path (default: root) - `recursive`: List recursively (default: `false`) - `maxDepth`: Max depth for recursion (default: 3) ## Data Storage All data is stored locally and created automatically on first run: | Path | Purpose | |------|---------| | `~/.config/onboarded-mcp/config.json` | User configuration | | `~/.cache/onboarded-mcp/` | Cached OpenAPI specs | | `~/.local/share/onboarded-mcp/state.db` | SQLite database for entity memory | ### Viewing Stored Entities ```bash # Query all entities sqlite3 ~/.local/share/onboarded-mcp/state.db "SELECT * FROM entities;" # Interactive mode sqlite3 ~/.local/share/onboarded-mcp/state.db ``` ## Security - Tokens are stored in macOS Keychain, never in files - Tokens never appear in MCP tool arguments or responses - Authorization headers are redacted in dry-run output - Shares credentials with `onboarded-cli` — authenticate once, use everywhere ## Development ```bash npm run build # Compile TypeScript npm run dev # Watch mode npm run typecheck # Type checking only ```