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:

Ask where to install (default: ./onboarded-mcp in the current directory)
Clone this repository
Run npm install and npm run build
Add the server to Warp's MCP config (~/.warp/mcp.json)
Optionally configure the Onboarded repo path for repo_read tool

After setup completes:

Restart Warp to load the MCP server
Authenticate: onboarded auth login <profile-name>

Manual Setup

If you prefer to set up manually:

# 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:

{
  "mcpServers": {
    "onboarded": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/onboarded-mcp/dist/index.js"]
    }
  }
}

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

{
  "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

# 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