Skip to main content
Glama

imperal-mcp

Build, ship, and run real cloud apps on Imperal — straight from your AI agent.

imperal-mcp puts the app-building power of Imperal Cloud — the ICNLI AI Cloud OS that Webbee 🐝 runs on — inside any MCP-capable agent. Connect it to Claude, Claude Code, Codex, Cursor, Gemini CLI, Cline, Windsurf, or Goose, sign in with your own Imperal account, and your agent can design, deploy, and operate real cloud apps for you — data, logic, and UI included — without ever leaving the chat.

You describe what you want. Your agent builds it. Imperal runs it.


What you can do

Tell your agent what you want — and it builds it on Imperal, end to end:

  • Design an app from a description — its data/entities, the functions that act on them, and the UI panels that render them, as one clean declarative spec.

  • Validate it instantly against the live Imperal schema, before anything ships.

  • Smoke-test a function in an isolated sandbox and see it actually work.

  • Deploy it live to your Imperal account — instantly available, fleet-wide.

  • List & inspect every app you've built.

  • Run your apps — query their data through their own tools, right from the agent.

Apps your agent can build in a single flow:

  • a habit / workout / reading tracker with list + detail views

  • a personal CRM or contacts book

  • a snippet vault or bookmark manager

  • a lightweight expense or invoice log

  • a notes / tasks / journal app

  • …any data-backed app with screens and actions you can describe in plain words.


Related MCP server: FastApply MCP Server

How it works

Your client's own LLM authors the app; imperal-mcp gives it the rails. It reads the IR spec and worked examples, validates the draft against the live schema, smoke-tests it, and deploys it to the cloud — no hand-written deployment scripts, no YAML wrangling. The heavy lifting — orchestration, hosting, scaling, the kernel — is Imperal's. Your agent just describes the app; the kernel makes it real.


Quick-add to your agent

Client

One-liner

Cursor

Add to Cursor

Claude Code

/plugin marketplace add imperalcloud/imperal-mcp then /plugin install imperal-mcp@imperal

Everything else

See per-client config

Install imperal-mcp and sign in first — see below.


Install & sign in

pipx install imperal-mcp      # or: pip install --user imperal-mcp
imperal-mcp login             # opens your browser to sign in to Imperal

login stores credentials in ~/.imperal/credentials.json and auto-refreshes your access token — no manual token management. Sign out any time:

imperal-mcp logout

That's it — every supported client uses the same imperal-mcp binary and the same stored sign-in.


Your first app (60 seconds)

  1. Install + imperal-mcp login (above), and add it to your agent.

  2. Ask your agent, in plain language:

    "Build me a habit tracker — I want to add habits, mark them done each day, and see today's summary. Then deploy it."

  3. Your agent authors the app, validates it, smoke-tests a function, and deploys it to your Imperal account. It comes back with the live app and its tools — ready to use.

Want to iterate? Just keep talking: "add a weekly streak view", "now build me an expense tracker too."


Per-client config

All clients use the same installed binary — imperal-mcp — and the same credentials from imperal-mcp login.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "imperal": { "command": "imperal-mcp" }
  }
}

Claude Code

/plugin marketplace add imperalcloud/imperal-mcp
/plugin install imperal-mcp@imperal

Or add directly to your project .mcp.json:

{
  "mcpServers": {
    "imperal": { "command": "imperal-mcp" }
  }
}

Cursor

Click the Add to Cursor button above, or add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "imperal": { "command": "imperal-mcp" }
  }
}

Codex (OpenAI)

Add to ~/.codex/config.toml:

[mcp_servers.imperal]
command = "imperal-mcp"

Gemini CLI

{
  "mcpServers": {
    "imperal": { "command": "imperal-mcp" }
  }
}

Cline

In VS Code, add to Cline's MCP server list:

{
  "imperal": { "command": "imperal-mcp", "disabled": false }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "imperal": { "command": "imperal-mcp" }
  }
}

Goose (Block)

Add a StandardIO extension in Goose settings:

{ "type": "stdio", "name": "imperal", "cmd": "imperal-mcp", "args": [] }

Tools

Tool

What it does

validate_ir(app_ir)

Validate an app.ir.json — envelope + every declarative step. Returns {valid, issues}.

smoke_ir(app_ir, function, args?)

Run one function in an isolated store and report {ok, result, trace}.

deploy_ir(app_ir, app_id)

Deploy an app into your account (creates the app record if needed) — live instantly.

list_apps()

List your developer apps.

get_app(app_id)

Get one app's manifest + tools.

run_read_tool(app_id, function, args?)

Run one of a deployed app's read tools to fetch its data.

Resources

URI

Description

imperal://ir-spec

The IR specification — structure, fields, action vocabulary.

imperal://ui-catalog

All ui.* components usable in panels and render steps.

imperal://examples

A worked app.ir.json (link-saver) to start from.

Prompt

build_imperal_app — step-by-step guidance for an LLM to go from intent to a deployed app: read the spec, author the IR, validate, smoke-test, deploy.


Configuration

Variable

Default

Purpose

IMPERAL_API_URL

https://auth.imperal.io

Auth / API base URL

IMPERAL_PANEL_URL

https://panel.imperal.io

Panel base URL

IMPERAL_TOKEN

(not set)

Optional token for CI / headless use — set it to skip browser login

For CI or headless environments, set IMPERAL_TOKEN to a token from panel.imperal.io → Developer → Access tokens.


Privacy & security

You sign in with your own Imperal account (browser OAuth). Credentials live locally at ~/.imperal/credentials.json (0600) and refresh automatically — nothing is shared with third parties and there's no telemetry. Read responses are PII-masked before they reach the LLM. Full details: PRIVACY.md.



Development

git clone https://github.com/imperalcloud/imperal-mcp
cd imperal-mcp
pip install -e '.[dev]'
python -m pytest

Built on Imperal Cloud — the AI Cloud OS. 🐝

Available Tools

6 tools
deploy_irA

Deploy an app.ir.json into the caller's account (creates the app record if needed).

ParametersJSON Schema
NameRequiredDescriptionDefault
app_irYes
app_idYes

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description partially discloses behavior by noting it creates the app record if needed. However, it omits other behavioral traits such as whether it updates existing apps, permissions required, or potential destructive actions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that conveys the core action and side-effect without unnecessary words or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (2 parameters, nested object, no output schema), the description covers the basic intent but lacks parameter details, return value info, and error handling guidance. It is minimally adequate but not comprehensive.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 0% description coverage for parameters, and the description only references 'app.ir.json' loosely related to app_ir. It does not explain what app_ir is or the role of app_id, leaving the agent without semantic guidance.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action 'Deploy an app.ir.json' and specifies the target 'into the caller's account' with a side-effect note. This distinguishes it from sibling tools like get_app, list_apps, validate_ir, etc.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for deployment but does not explicitly state when to use or avoid this tool versus alternatives. No exclusion criteria or alternative guidance is provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_appA

Get one app's manifest + tools (with action_type) (PII-masked).

ParametersJSON Schema
NameRequiredDescriptionDefault
app_idYes

TDQS

A3.8/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses that the response is PII-masked, which is a behavioral trait. However, it does not explicitly state that the tool is read-only or address authentication/rate limits. For a simple get tool, this is adequate but not exhaustive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence of 6 words, no wasted words. It conveys the key purpose and the notable PII-masking feature concisely.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with 1 parameter and no output schema or annotations, the description is minimal. It covers the basic purpose and return content but lacks guidance on parameter semantics and error cases. It is adequate but not thorough.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% (no parameter description in the description). The single parameter app_id is not explained beyond its name and type. With low coverage, the description should add meaning (e.g., how to obtain app_id), but it does not, leaving the agent to infer from the schema alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Get' and the resource 'one app', and specifies what is returned (manifest, tools with action_type, PII-masked). This distinguishes it from sibling tools like list_apps (which lists all apps) and run_read_tool (which runs a tool).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage: when you need details of a specific app by app_id. However, it does not provide explicit guidance on when to use this vs alternatives (e.g., list_apps), nor does it mention prerequisites or when not to use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_appsA

List the caller's developer apps (PII-masked).

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.5/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the full burden of behavioral disclosure. It only states the action and the PII-masking behavior, lacking details on read-only nature, authentication requirements, rate limits, or potential side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that front-loads the key information. Every word is necessary and there is no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has low complexity with no parameters and no output schema. The description provides the basic function but does not specify the output fields or any sorting/filtering behavior. While adequate for a simple list, it could be more complete to reduce ambiguity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are zero parameters, and the schema is empty with full coverage. The description adds value by noting that the output is PII-masked, which is not indicated by the schema, so it provides meaningful context beyond the structured data.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'List' and identifies the resource as 'caller's developer apps' with the qualifier 'PII-masked'. It clearly distinguishes this from sibling tools which focus on different operations like deploying or validating IR.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives. The description does not mention prerequisites, exclusions, or any context about appropriate usage scenarios.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

run_read_toolB

Run a READ-only tool of a deployed app (refuses write/destructive).

ParametersJSON Schema
NameRequiredDescriptionDefault
app_idYes
functionYes
argsNo

TDQS

B3.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses the behavioral trait of refusing write/destructive actions, but with no annotations, it lacks details on what happens if a write is attempted, rate limits, or authentication requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very short but fails to provide essential information about parameters and usage, making it under-specified rather than concise. It is front-loaded but incomplete.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has three parameters, no annotations, and no output schema, the description is incomplete. It does not explain what 'args' is for, what 'function' values are valid, or how to find them.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description adds no meaning to any of the three parameters (app_id, function, args). The description does not explain what these parameters are or how to use them.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it runs a READ-only tool of a deployed app, specifying the verb 'run' and resource 'READ-only tool'. It distinguishes from sibling tools that likely involve writing or destructive actions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use (for read operations) and when not (refuses write/destructive). It does not explicitly name alternatives but the sibling tools suggest other operations (deploy, smoke, validate).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

smoke_irA

Run one function of an app.ir.json in an ISOLATED store and report {ok,result,trace}.

ParametersJSON Schema
NameRequiredDescriptionDefault
app_irYes
functionYes
argsNo

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must cover behavior. It mentions 'ISOLATED store' indicating safety from side effects, and output format {ok,result,trace}. However, it lacks details on auth requirements, rate limits, or what happens to the store after execution.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, no fluff. Core information (verb, resource, isolation, output) is front-loaded. Each word serves a purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description helpfully includes output format. But with nested objects and no parameter details, the description leaves gaps. The isolated store hint is valuable but overall could be more comprehensive.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so description must compensate. It does not explain the app_ir object structure, function name format, or how args should be provided. The description uses general terms 'one function' without clarifying parameter semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool runs a function from an app.ir.json in an isolated store and reports the result in a structured format. It distinguishes itself from siblings like deploy_ir (deployment) and validate_ir (validation) by focusing on isolated execution.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies use for testing functions in an isolated environment but does not explicitly state when to use or avoid this tool compared to alternatives like run_read_tool or deploy_ir. No when-not-to-use or prerequisite info.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

validate_irC

Validate an app.ir.json locally (envelope + every declarative step).

ParametersJSON Schema
NameRequiredDescriptionDefault
app_irYes

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must fully disclose behavioral traits. It only mentions 'validate locally' and 'envelope + every declarative step' but omits details on what validation entails, side effects, or output behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence, but it is underspecified and lacks structure. It sacrifices necessary details for brevity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of annotations, output schema, and parameter descriptions, the description is insufficient for an agent to correctly invoke the tool. It fails to provide parameter guidance and behavioral context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single parameter 'app_ir' is an object with no description in the schema (0% coverage). The description does not explain what this parameter should contain, leaving the agent with only the type information.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Validate' and the resource 'app.ir.json', with additional scope clarification 'locally (envelope + every declarative step)'. It effectively distinguishes from sibling tools like deploy_ir and smoke_ir.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies local validation before deployment but does not explicitly state when to use this tool versus alternatives like deploy_ir or smoke_ir. No when-not or alternative guidance is provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 6 tool updatesv0.1.0
    • First observeddeploy_ir
    • First observedget_app
    • First observedlist_apps
    • First observedrun_read_tool
    • First observedsmoke_ir
    • First observedvalidate_ir

TDQS

A3.5/5.0
Disambiguation5/5

Each tool targets a distinct action: deploy, get, list, run read-only, smoke test, and validate. No overlapping purposes.

Naming Consistency4/5

Most tools follow verb_noun pattern (deploy_ir, get_app, list_apps, validate_ir), but 'run_read_tool' uses an adjective and 'smoke_ir' uses an unconventional verb, creating minor inconsistency.

Tool Count5/5

With 6 tools, the server covers key operations for managing IR-based apps without being overwhelming. The scope is well-balanced.

Completeness3/5

Core workflows are covered (validation, deployment, listing, reading), but missing update/delete for apps and any write tool execution, leaving notable gaps for full lifecycle management.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/imperalcloud/imperal-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server