OCP MCP Server - Developer Guide | OCP® Learning Center

OCP MCP Server Overview

The OCP MCP Server lets you build, deploy, and test OCP agents directly from a chat prompt in tools that developers already use such as Claude Desktop, Claude Code, Cursor, VS Code, and Codex. Instead of navigating the platform console step by step, you describe your needs in plain language, and the assistant executes the tasks through OCP's tools.

The OCP MCP Server exposes the Omilia Cloud Platform to any Model Context Protocol client. From a single chat prompt you can build agents, attach knowledge, deploy, and converse with the deployed app. The server is a stateless tool catalogue; your client's LLM is the agent.

Building a working voice or chat agent can be done through a single conversation. Someone can go from "I want an agent that does X" to a live, talking prototype in minutes rather than hours. And with Claude interfaces on mobile, pc and cursor, agents can be made from virtually anywhere at any time.

For the business, that means demos and proofs-of-concept get into a customer's hands far faster, the people who can build them aren’t limited to platform specialists, and developers can work with OCP without leaving their everyday tools.

Prerequisites

An OCP Personal Access Token (IAM → Personal Access Tokens) or an OCP username + password
The base URL of your OCP environment (for example, https://us1-m.ocp.ai)
An MCP-compatible client (Claude Desktop, Claude Code, Cursor, VS Code, Codex)
Node.js 20 or higher and uv installed on $PATH

Authentication

Two authentication paths are supported. When both are set, PAT takes priority.

Personal Access Token

set OCP_BASE_URL
OCP_ACCESS_TOKEN

Get a PAT from IAM → Personal Access Tokens in your OCP environment.

Keycloak username / password

set OCP_BASE_URL,
OCP_USERNAME,
OCP_PASSWORD, and
OCP_KEYCLOAK_REALM

The server exchanges the credentials for a token on first use and refreshes proactively. Use OCP_KEYCLOAK_REALM=master for Swarm (legacy) deployments and OCP_KEYCLOAK_REALM=ocp for Kubernetes deployments. For more info read API Authentication

Installation

The server is distributed straight from GitHub. Every command below runs github:omilia/mcp via npx (no npm registry account or login required).

Interactive wizard (recommended)

Run init with no flags and answer the prompts:

npx github:omilia/mcp init

The wizard walks you through:

Client: pick Claude Code or Claude Desktop.
Authentication: choose PAT or Keycloak username/password.
Credentials: enter your base URL and token (or username/password/realm). Secret input is not echoed to the terminal.
Confirmation: review a summary of what will be installed, with secrets masked.
Install + verify: the wizard installs the server, then checks prerequisites (Node 20+, uv) and runs a smoke test, ending with a clear PASS/FAIL summary.

The wizard currently targets Claude Code and Claude Desktop.

For Cursor, VS Code, and Codex, use the flag-driven --print / --write methods below.

Flag-driven installation

Three flag-driven methods are also supported; pick the one that fits your client and workflow.

Method	Best for	How
Manual config	Anyone comfortable editing JSON; works in all supported clients	Run `npx github:omilia/mcp init --client <name> --print`, then paste the output into the client's config file
CLI installer	Developers who want a one-command setup	Run `npx github:omilia/mcp init --client <name> --write`
`.mcpb` bundle	Claude Desktop users / environments without `npx`	Drag-and-drop into Claude Desktop → Settings → Connectors; GUI prompts for credentials

Supported client names: claude, claude-code, cursor, vscode, codex. Config file locations:

Client	Config file
Claude Desktop	`~/Library/Application Support/Claude/claude_desktop_config.json`
Claude Code	installed via `claude mcp add` (see below); `~/.claude.json` or per-project `.claude/mcp.json` when pasting `--print` output manually
Cursor	`~/.cursor/mcp.json`
VS Code	`.vscode/mcp.json` (workspace) or user `settings.json`
Codex	`~/.codex/config.toml`

Claude Code uses claude mcp add. For Claude Code, the installer shells out to the official Claude Code CLI rather than writing a config file directly - equivalent to:

claude mcp add OCP --scope user \
  --env OCP_BASE_URL=your-ocp-base-url \
  --env OCP_ACCESS_TOKEN=your-ocp-access-token \
  -- npx -y github:omilia/mcp run

If the claude CLI is not on your $PATH, the installer prints the equivalent config snippet (with secrets masked) plus instructions instead of failing silently. The token is passed as a process argument array, never through a shell string.

For the other clients, the generated config snippet looks like this:

JSON

{
  "mcpServers": {
    "OCP": {
      "command": "npx",
      "args": ["-y", "github:omilia/mcp", "run"],
      "env": {
        "OCP_BASE_URL": "your-ocp-base-url",
        "OCP_ACCESS_TOKEN": "your-ocp-access-token"
      }
    }
  }
}

Replace the placeholder values with your actual OCP base URL and credentials before saving. See the Authentication section for the full set of supported env vars.

Verifying the Installation

When you use the interactive wizard, verification runs automatically. it confirms Node 20+ and uv are on your $PATH (reporting an install hint if either is missing), starts the server, and confirms its tools are reachable and prints a PASS/FAIL summary before it exits. No credentials appear in that output.

To manually check after restarting your client, you can smoke-test connectivity from a chat prompt:

Use the read_guide tool to show me the index of available OCP guides.

You should see four guides listed: index, build_concierge_app, add_knowledge, test_and_improve. If the tool list is empty, double-check your configuration and restart your client.

MCP Prompts

The server publishes four MCP prompts, parameterized conversation starters that clients surface as slash-commands or one-click buttons. They encode the recommended tool sequences for canonical OCP journeys.

Prompt	Arguments	What it kicks off
`build_concierge_app`	`group`, `name`, `instructions` (default supplied)	Create app → create Concierge agent → wire into canvas → set instructions → deploy → smoke-test with `talk_to_app`
`add_knowledge`	`agent_id`, plus either `source_url` + `pathfinder_project_id` or `existing_kb_id`	Attach a Pathfinder FAQ ingested from a URL, or wire an existing knowledge base, then redeploy and verify with `talk_to_app`.
`test_and_improve`	`app_id`, `scenario` (default supplied)	Multi-turn smoke test via `talk_to_app`, then propose and apply instruction or knowledge refinements.
`show_tools`	none	Print all available OCP tools as a table. Useful for discovery at the start of a session.

A worked end-to-end example of the build_concierge_app journey with full tool payloads is in Example: Build, Deploy, and Test a Concierge App.

Tool Reference

We are offering a variety of tools across the following groups.

Discovery & guidance

Tool	What it does
`read_guide(name?)`	Returns a step-by-step markdown recipe for a canonical journey. Call at the start of any agent-build session. Omit `name` to list available guides.
`list_groups()`	Lists the OCP groups your account can access. Automatically used when you omit `group` from a create tool.

Building & deploying apps

Tool	What it does
`create_orchestrator_app(name, group?)`	Create a new Orchestrator application. Omit `group` to auto-detect.
`create_agent(name, group?, agent_type)`	Create a Concierge (`"concierge"`) or Task (`"task"`) agent.
`add_concierge_to_orc_app(app_id, agent_id)`	Wire a Concierge agent into an app canvas. Call once per new app.
`update_agent_instructions(agent_id, instructions)`	Set the agent's persona and instructions. Required before deploy.
`deploy_orc_app(app_id)`	Deploy the app. Wait ~10 s before testing.
`search_orchestrator_apps(search_term?)`	Find existing apps by name.
`get_orchestrator_app(app_id)`	Get app metadata and canvas contents.
`list_agents()`	List all agents in scope.

Testing deployed apps

Tool	What it does
`talk_to_app(app_id, message, session_id?)`	Send a message to a deployed app and get the agent's reply. Supports multi-turn conversations .

Knowledge & Pathfinder

Tool	What it does
`create_pathfinder_project(name, group)`	Create a Pathfinder project to hold a FAQ knowledge base.
`list_pathfinder_projects(search_term?)`	List existing Pathfinder projects.
`add_faq_to_agent(url, pathfinder_project_id, agent_id)`	Crawl a URL via Pathfinder and attach the resulting FAQ to an agent.
`list_knowledge_bases()`	List existing FAQ vector stores.
`add_knowledge_base_to_agent(agent_id, knowledge_base_id)`	Attach an existing knowledge base to an agent.

miniApps & webservice agents

Tool	What it does
`search_miniapps(search_term?)`	Find miniapps by name.
`get_miniapp(miniapp_id)`	Retrieve full miniapp data.
`set_miniapp_prompt(miniapp_id, prompt_type, prompt, locale?)`	Set welcome, initial, error, or reaction prompts on a miniapp.
`create_webservice_miniapp(end_point_url, group, name)`	Create a webservice miniapp from a URL endpoint.
`edit_webservice_miniapp(miniapp_id, ...)`	Update the URL, method, or other properties of an existing webservice miniapp.
`create_webservice_agent(miniapp_id, group, agent_name, ...)`	Create a Task agent wired to a webservice miniapp.
`add_tool_to_webservice_agent(agent_id, miniapp_id, ...)`	Add an additional tool to an existing webservice agent.
`add_escalation_queue_to_agent(agent_id, queue_info)`	Add human-escalation queues to an agent.
`add_knowledge_base_to_agent(agent_id, knowledge_base_id)`	Attach an existing knowledge base to an agent.
`add_agent_to_concierge(agent_id, group, ...)`	Register a Task agent as a sub-agent of the Concierge in a group.
`update_concierge(concierge_agent_id, agents)`	Bulk-replace the sub-agent list of a Concierge agent.

Insights & integrations

Tool	What it does
`search_dialog_logs(dialog_group?, apps?, from_date?, to_date?, ...)`	Search dialog sessions by group, app, date range, or ANI.
`get_dialog_logs(dialog_id)`	Get the full log for a specific dialog.
`search_numbers(search_term?)`	Search phone numbers.
`search_variable_collections(search_term?)`	Search variable collections in Environments Manager.
`get_collection_variables(collection_id)`	List all variables in a collection.

Metrics

Tool	What it does
`list_metrics_tables()`	List all queryable OCP metrics table names for the authenticated tenant.
`describe_metrics_table(table_name)`	Return a table’s columns with the dimension/measure classification (`pk=true`=dimenion, `pk=false`=measure).
`query_metrics_aggregation(table, measure, ocp_group_names, …)`	Compute overall metrics totals scoped to OCP groups; operators: sum/avg/min/max/count; defaults to last 24h
`query_metrics_grouped(table, measures, group_by, ocp_group_names, …)`	Break totals down per dimension value; set `percentage=true` for server side distribution.

Multi-turn Chat

talk_to_app supports multi-turn conversations via OCP's session resumption protocol. Omit session_id on the first call; pass the returned value on each follow-up turn. OCP preserves conversational context (history, slots, named entities) server-side across resumed WebSocket connections:

# Turn 1 — start a new session
result = talk_to_app(app_id="my_app", message="Hello")
session_id = result["session_id"]

# Turn 2 - agent retains context from turn 1
result = talk_to_app(app_id="my_app", message="What can you help with?", session_id=session_id)

# Turn 3 - and so on
result = talk_to_app(app_id="my_app", message="Tell me more about option 1", session_id=session_id)