imperal-mcp
OfficialBuild, validate, deploy, and operate cloud apps on Imperal Cloud directly from an AI agent using these capabilities:
validate_ir— Validate anapp.ir.jsonspecification against the live Imperal schema, returning a{valid, issues}report before deploying anything.smoke_ir— Smoke-test a single function in an isolated sandbox, returning{ok, result, trace}for debugging.deploy_ir— Deploy a complete app IR to your Imperal account (auto-creates the app record if needed), making it live instantly.list_apps— List all developer apps in your Imperal account (with PII masking applied).get_app— Retrieve a specific app's full manifest and available tools, with PII masking.run_read_tool— Execute a read-only tool on a deployed app to query live data; write/destructive operations are refused for safety.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@imperal-mcpvalidate and deploy my app.ir.json"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 | |
Claude Code |
|
Everything else |
Install
imperal-mcpand 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 Imperallogin stores credentials in ~/.imperal/credentials.json and auto-refreshes your access token — no manual token management. Sign out any time:
imperal-mcp logoutThat's it — every supported client uses the same imperal-mcp binary and the same stored sign-in.
Your first app (60 seconds)
Install +
imperal-mcp login(above), and add it to your agent.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."
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@imperalOr 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 an |
| Run one function in an isolated store and report |
| Deploy an app into your account (creates the app record if needed) — live instantly. |
| List your developer apps. |
| Get one app's manifest + tools. |
| Run one of a deployed app's read tools to fetch its data. |
Resources
URI | Description |
| The IR specification — structure, fields, action vocabulary. |
| All |
| A worked |
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 |
|
| Auth / API base URL |
|
| Panel base URL |
| (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.
Links
Imperal Cloud — https://imperal.io
Panel (your apps, tokens, billing) — https://panel.imperal.io
ICNLI (the open protocol behind it, CC BY-SA) — https://icnli.org
Development
git clone https://github.com/imperalcloud/imperal-mcp
cd imperal-mcp
pip install -e '.[dev]'
python -m pytestBuilt on Imperal Cloud — the AI Cloud OS. 🐝
Available Tools
6 toolsdeploy_irA
Deploy an app.ir.json into the caller's account (creates the app record if needed).
| Name | Required | Description | Default |
|---|---|---|---|
| app_ir | Yes | ||
| app_id | Yes |
TDQS
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.
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.
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.
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.
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.
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).
| Name | Required | Description | Default |
|---|---|---|---|
| app_id | Yes |
TDQS
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.
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.
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.
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.
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.
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).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
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.
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.
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.
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.
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.
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).
| Name | Required | Description | Default |
|---|---|---|---|
| app_id | Yes | ||
| function | Yes | ||
| args | No |
TDQS
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.
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.
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.
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.
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.
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}.
| Name | Required | Description | Default |
|---|---|---|---|
| app_ir | Yes | ||
| function | Yes | ||
| args | No |
TDQS
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.
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.
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.
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.
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.
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).
| Name | Required | Description | Default |
|---|---|---|---|
| app_ir | Yes |
TDQS
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.
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.
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.
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.
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.
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.
6 tool updates
v0.1.0- First observed
deploy_ir - First observed
get_app - First observed
list_apps - First observed
run_read_tool - First observed
smoke_ir - First observed
validate_ir
TDQS
Each tool targets a distinct action: deploy, get, list, run read-only, smoke test, and validate. No overlapping purposes.
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.
With 6 tools, the server covers key operations for managing IR-based apps without being overwhelming. The scope is well-balanced.
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
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
Build, validate, deploy — HTTP APIs, cron jobs, webhooks and MCP tools — from your AI client.
Deploy and manage your apps, databases, storage, and scheduled jobs from your AI agent
AppDeploy turns app ideas described in AI chat into live full-stack web applications
Turn PRDs and product ideas into structured specs so coding agents build your intent, not theirs.
Related MCP Servers
- AlicenseAqualityFmaintenanceUnleashes LLM-powered agents to autonomously execute and debug web apps directly in your code editor, with features like webapp navigation, network traffic capture, and console error collection.21,240Apache 2.0
- AlicenseCqualityDmaintenanceEnables AI-powered code editing with preview and validation capabilities through FastApply language models. Features automatic backups, atomic file operations, and support for multiple FastApply-compatible backends like LM Studio and Ollama.23MIT
- FlicenseNot gradedqualityNot gradedmaintenanceIntegrates Laminar workspaces with AI editors to manage workflows, steps, and configuration stores. It allows users to execute, monitor, and debug workflow executions through natural language commands.3081-
- FlicenseNot gradedqualityDmaintenanceEnables LLM-powered code analysis, generation, debugging, and context management through MCP integration with IDEs like Cursor and Claude Desktop.-
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
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