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

# 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