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 — tokens never appear in MCP tool calls or responses.

Setup

Prerequisites

• Node.js 18+

• git

• onboarded-cli — github.com/OnboardedInc/Onboarded-CLI

Quick Setup (Recommended)

The onboarded CLI handles everything automatically:

onboarded mcp setup

This interactive command will:

1. Clone this repository to ~/.onboarded-mcp

2. Run npm install and npm run build

3. Add the server to your MCP client config

4. Optionally configure the Onboarded repo path for repo_read tool

After setup completes:

1. Restart your MCP client (Warp, Claude Desktop, etc.) to load the server

2. Authenticate: onboarded auth login <profile-name>

Manual Setup

If you prefer to set up manually:

# Clone and build into your home directory
git clone https://github.com/OnboardedInc/onboarded-mcp.git ~/.onboarded-mcp
cd ~/.onboarded-mcp
npm install
npm run build

Then add the server to your MCP client config.

Warp (~/.warp/mcp.json):

{
  "mcpServers": {
    "onboarded": {
      "command": "node",
      "args": ["/Users/YOUR_USERNAME/.onboarded-mcp/dist/index.js"]
    }
  }
}

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "onboarded": {
      "command": "node",
      "args": ["/Users/YOUR_USERNAME/.onboarded-mcp/dist/index.js"]
    }
  }
}

Important: Use the full absolute path (e.g. /Users/yourname/.onboarded-mcp/...). Do not use ~ — Node.js does not expand tilde in arguments.

Optionally create ~/.config/onboarded-mcp/config.json for repo_read tool:

{
  "onboardedRepoPath": "/Users/YOUR_USERNAME/path/to/onboarded"
}

Available Tools

Discovery Tools

Execution Tools

State Tools

Repository Tools (optional)

Requires onboardedRepoPath to be configured.

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:

Viewing Stored Entities

# 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

npm run build      # Compile TypeScript
npm run dev        # Watch mode
npm run typecheck  # Type checking only