mc8yp
mc8yp is an MCP server that lets AI agents discover and execute the Cumulocity API through sandboxed JavaScript, locally or as a deployed microservice.
Run async JavaScript via
codemode, usingc8yand per-microservice typed namespaces to call Cumulocity APIs.Discover APIs with
codemode.searchandcodemode.describe, and read prose docs withdocs.searchanddocs.read.Check stored credentials/current tenant and switch or clear the active tenant with
statusandset-active-tenant; refresh tenant API discovery.Use as a local CLI over stdio with OS keyring credentials, or deploy as a Cumulocity microservice over HTTP using the caller’s
Authorizationheader.Add it to Claude Code, Claude Desktop, or other MCP clients.
Restrict or allow operations by HTTP method and path via CLI flags or microservice headers/query parameters.
Auto-discover tenant microservices that expose OpenAPI specs or MCP servers; attach external MCP servers.
Microservice mode can auto-register with AI Agent Manager and optionally provide a
sandboxshell.
Click on "Deploy 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., "@mc8yp list all devices in inventory"
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.
mc8yp
An MCP server that gives AI agents the full Cumulocity API through one tool, codemode.
The agent writes a short async JavaScript function. It runs in a sandbox where every API is a typed namespace (c8y for core, plus one per microservice on the tenant, such as dtm), together with search and docs helpers to find the right method:
async () => {
const { results } = await codemode.search('managed objects')
const devices = await c8y.getManagedObjectCollectionResource({ pageSize: 20 })
return devices.managedObjects?.map((d) => ({ id: d.id, name: d.name }))
}Any microservice on the tenant that ships an OpenAPI spec or an MCP server is picked up automatically. No rebuild needed.
CLI or microservice
CLI | Microservice | |
Runs | Locally, over stdio | Inside Cumulocity, over HTTP at |
Credentials | OS keyring ( | The caller's |
Tenant | The agent picks one with | Fixed by the deployment |
Extra tools |
| Optional |
Platforms | macOS, Linux, WSL 2 | Any Cumulocity tenant |
Use it for | Local development with Claude Code or similar | Shared and production agents, AI Agent Manager |
Related MCP server: @restforge-dev/mcp-server
Microservice
Download the release zip from GitHub Releases.
Upload it in Cumulocity Application Management and subscribe it.
Point your agent at
https://<tenant>.cumulocity.com/service/mc8yp-server/mcp.
The app auto-registers with AI Agent Manager, so no manual MCP server entry is needed there.
CLI
pnpm dlx mc8yp creds add # store tenant URL, user and password in the OS keyring
pnpm dlx mc8yp creds list
pnpm dlx mc8yp creds removeUsers with two-factor authentication are prompted for their code; the agent's MCP client asks for a new one when the session expires.
Adding credentials does not select a tenant. The agent calls status to see stored tenants and set-active-tenant to pick one. The choice is saved per working directory, so agents in different projects do not switch each other's tenant. Every codemode result starts with the tenant it ran against.
Add to Claude
Claude Code, local CLI:
claude mcp add mc8yp -- pnpm dlx mc8yp
# available in every project
claude mcp add -s user mc8yp -- pnpm dlx mc8ypClaude Code, deployed microservice:
claude mcp add --transport http mc8yp \
https://<tenant>.cumulocity.com/service/mc8yp-server/mcp \
--header "Authorization: Bearer <token>"Claude Desktop or any other stdio client:
{
"mcpServers": {
"mc8yp": { "command": "pnpm", "args": ["dlx", "mc8yp"] }
}
}Everything after -- in claude mcp add goes to mc8yp, so access rules (below) go there too.
Restrict access
Two rule types, set per connection:
Restrictions block matching operations.
Allow rules block everything that does not match one of them.
Restrictions win when both match. A rule is [METHOD:]/path, where * matches within one path segment and ** matches any number of segments.
Rule | Means |
| every method on |
| only GET on |
| only DELETE on |
CLI: -r for restrictions, -a for allow rules.
# read-only agent
claude mcp add mc8yp -- pnpm dlx mc8yp \
-a "GET:/inventory/**" -a "GET:/alarm/**" -a "GET:/measurement/**"
# no inventory deletes, no user management
pnpm dlx mc8yp -r "DELETE:/inventory/**" -r "/user/**"Microservice: mc8yp-restriction and mc8yp-allow headers (repeated or comma-separated), or the r and a query parameters.
POST /service/mc8yp-server/mcp
mc8yp-allow: GET:/inventory/**, GET:/alarm/**
mc8yp-restriction: /user/**Blocked operations are hidden from the agent's search and are refused before any request reaches Cumulocity. Rules apply to OpenAPI-backed APIs only, not to MCP-backed ones. See <docs/access-policy.md> for the full syntax and the MCP caveat.
More
External MCP servers: attach third-party MCP servers to a connection
Advanced: how discovery works, the
sandboxshell, MCP-backed services, the bundled core spec,--spec
Development
Requires Node.js 24 or later and pnpm.
pnpm install
pnpm test:run
pnpm lint:fix
pnpm typecheck
pnpm build # CLI in dist/, server bundles in .output/<version>/
pnpm package:microservices # one Cumulocity zip per bundled core versionLicense
MIT
Available Tools
3 toolscodemodeCumulocity Code ModeA
Read first. Every result starts with a marker line: either Executed against tenant: <url> or a no-active-tenant notice. Verify it matches the tenant you intend to act on before reporting the result. The active tenant is global to this CLI session and can be flipped between calls by set-active-tenant. Without an active tenant, discovery (codemode/docs) works against bundled reference snapshots but live API calls fail with a missing-auth error — call status and set-active-tenant to connect.
A method visible in discovery may still return 404 when the service is not actually installed on the current tenant.
Run an async JavaScript function against the Cumulocity API. Discovery, documentation, and typed API calls all happen inside one function — find what you need and call it in the same run.
The expensive mistake is a hasty API call: an unparameterized request returns large payloads that flood your context. search and describe are cheap — spend calls there first.
Do NOT rely on prior knowledge of these APIs and do not assume anything: the available namespaces and their capabilities are tenant-specific and discovered at runtime. What you think you know about an API may be outdated or may be outclassed by a service on this tenant you have never seen. Verify through search, describe, and docs.
Available globals (do NOT declare these as function parameters):
declare const codemode: {
/** Ranked fuzzy search over API method names, REST paths, and summaries. Returns the top 20 by score. Pass several phrasings at once — results are unioned. */
search: (query: string | string[]) => Promise<{
results: Array<{ target: string, namespace: string, method: string, httpMethod?: string, apiPath?: string, summary?: string, score: number }>
total: number
truncated: boolean
}>
/**
* No target: overview of the namespaces on THIS tenant and their
* responsibilities — ALWAYS your first call.
* "namespace.method": the typed interface for ONE method — signature,
* input/output types with OpenAPI docs as JSDoc, related doc ids.
* Array of method targets (max 5): describe a shortlist in one call and
* COMPARE their input types before picking.
* "namespace": every method in it, ONE LINE each (name, path, summary) and
* NO types — for surveying a domain. The overview's method count is the
* cost; on a large namespace search first.
*/
describe: (target?: string | string[]) => Promise<
{ target: string, kind: 'overview' | 'namespace' | 'method', content: string }
| Array<{ target: string, kind: 'overview' | 'namespace' | 'method', content: string }>
>
}
declare const docs: {
/** Fuzzy full-text search over prose documentation topics: domain query languages, concepts, API-area guides. Per-method details live in codemode.describe instead. */
search: (query: string, opts?: { limit?: number, fuzzy?: number, prefix?: boolean, minScore?: number, maxTextLength?: number }) => Promise<Array<{
id: string, title: string, text: string, truncated: boolean, kind: 'topic' | 'overview', namespace: string, score: number
}>>
/**
* Full untruncated text of a documentation entry. Return it WHOLE — never
* slice or truncate doc text: the crucial capability (an operator, a
* function, a constraint) is often documented near the end, and a blind
* cut loses exactly the part you searched for. Long doc topics are the
* one output where length is justified.
*/
read: (id: string) => Promise<{ id: string, title: string, text: string, kind: string, namespace: string }>
}
// API namespaces: `c8y` (Cumulocity core — always present) plus one global
// per microservice available on the current tenant (e.g. `dtm`), plus any
// external MCP server configured for this connection — each with one typed
// method per operation. `codemode.describe()` lists what this connection
// actually has. If a method seems missing, search with different wording; if
// it truly does not exist, say so instead of improvising:
// await c8y.getManagedObjectCollectionResource({ pageSize: 5 })Workflow — ALWAYS in this order: describe() → search → describe(shortlist) → call.
codemode.describe()(no target) — ALWAYS start here. It lists the API namespaces on THIS tenant with their responsibilities. A domain service (asset management, data preparation, …) usually has a far better API for its domain — server-side hierarchy queries, bulk operations — than composing the generic core API. Decide which namespaces could own the problem's domain, and search with each of their vocabularies.codemode.search(["phrasing 1", "phrasing 2"])— find candidate methods (top 20 by score). Results usually contain several overlapping endpoints (single-item, collection, count, by-external-id, bulk variants) — read all summaries and shortlist every candidate that could satisfy the request in ONE call, don't grab the first hit. If all results come from one namespace, re-check the overview — another namespace may own the domain with a stronger API. If the expected method is missing, re-search with other domain words before concluding it does not exist — checktotaltoo.codemode.describe(["ns.methodA", "ns.methodB"])(max 5) — ALWAYS describe before calling, and describe the whole shortlist in one call. Compare the input types: prefer the method whose parameters push the work to the server — query/filter parameters (especially ones marked@format c8y:queryor documenting a query grammar), hierarchy/recursive selectors, bulk endpoints — over methods that would force per-item calls or client-side filtering. Describing five candidates costs almost nothing; one wrong or unfiltered API call costs more context than all your discovery combined. If search keeps missing the domain's vocabulary,codemode.describe("<ns>")lists every method in that namespace one line each (no types) — the method count from step 1 is what it costs.docs.search("...")/docs.read(id)— when a parameter references domain syntax you don't know, read the docs before guessing values. Read doc texts to the END — never.slice()them: the operator or function you need is often documented in the later sections, and a blind cut loses exactly the crucial part.Call the winner:
await c8y.someMethod({ ...params, body })(path/query/header parameters andbodyshare one flat input object). ONE well-parameterized call beats fetching broadly and filtering in your code, and beats chains of per-item calls. If you catch yourself looping over items to call an API for each one, go back to step 1 — a collection, query, or bulk endpoint usually exists.Return only the data needed to answer — never return raw unfiltered collections.
Discovery and API calls can be combined in a single run. Methods blocked by the connection access policy are omitted from discovery entirely; a blocked live request fails with an explanatory message — that is a connection-level access restriction, not a Cumulocity API failure, and retrying will not help.
Your code must evaluate to an async function. Return the final value you want; on success it is returned in Toon format.
Examples:
async () => {
const { results } = await codemode.search('alarms by severity')
const { content } = await codemode.describe(results[0].target)
return content
}async () => {
return await c8y.getAlarmCollectionResource({ pageSize: 10, severity: 'MAJOR' })
}async () => {
const hits = await docs.search('inventory query language syntax')
return hits.length > 0 ? (await docs.read(hits[0].id)).text : 'no docs found'
}Inputs: code (required).
set-active-tenantSet Active TenantA
Set the Cumulocity tenant for this CLI session, or pass tenantUrl: null to clear the active tenant. The tenantUrl must match one returned by the status tool. The selection is persisted for the working directory this server was started in, so later sessions in the same project reuse it; sessions in other directories are never affected. Clearing falls back to bundled-only browsing — codemode discovery still works but live API calls are unavailable until a tenant is set again.
Inputs: tenantUrl (required).
statusmc8yp StatusA
Show the current CLI status: stored tenant credentials, which tenant the codemode tool will hit, and the API namespaces visible right now. If no tenant is active, codemode discovery falls back to all bundled OpenAPI snapshots and live API calls are unavailable — set-active-tenant must be called first. This tool also self-heals: if the active tenant has lost its stored credentials it is automatically reset before the status is reported.
Pass refresh: true to force a fresh API spec discovery against the active tenant. Use this after subscribing or unsubscribing a microservice in the tenant — otherwise discovered specs stay cached for 30 minutes. If no tenant is active, refresh: true is a noop.
Inputs: refresh.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
The three tools occupy clearly different roles: codemode executes code against the API, status reads/reports current state, and set-active-tenant mutates tenant selection. The one soft overlap is that status can 'self-heal' by resetting lost credentials, which brushes against set-active-tenant's clearing behavior, but the read-vs-write boundary is still clear from the descriptions.
Two tools are bare nouns (codemode, status) while one is a kebab-case verb-noun (set-active-tenant), so there is no single predictable pattern. Each name is individually readable and the inconsistency is mild rather than chaotic.
Three tools is lean for a gateway server, but codemode is a meta-tool that absorbs the entire discover-describe-call surface, so the real toolset is effectively unbounded through it. setup/status/execute is a defensible minimal triple; only slightly under a typical well-scoped count.
The session lifecycle is covered: check state (status), connect/switch (set-active-tenant), execute (codemode), plus cache refresh via status.refresh and tenant clearing via a null argument. The notable gap is credential/authentication setup — status references 'stored tenant credentials' but no tool exists to establish them, so onboarding a new tenant depends on out-of-band state.
Maintenance
Related MCP Connectors
MCP server for OpenAI API (chat completions, image generation, embeddings) via AceDataCloud
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
Hosted MCP server for live public-data APIs and Skills for AI agents.
One MCP server for the services your AI needs: memory, files, Microsoft 365, kanban and more.
Related MCP Servers
- AlicenseBqualityDmaintenanceProduction-grade MCP server that gives AI agents safe access to your local dev environment: filesystem, databases, processes, and OpenAPI specs.1540 npm4MIT
- AlicenseAqualityCmaintenanceMCP server that exposes RESTForge capabilities to AI agents, enabling them to set up, configure, generate code, and manage RESTForge projects through natural language.2944 npmMIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that gives AI agents full access to the Clever Cloud API through three tools: search, execute, and doc, using a code mode pattern to compose API commands.4Apache 2.0
- AlicenseNot gradedqualityDmaintenanceAn MCP server that enables AI agents to explore, search, and query API definitions from OpenAPI/Swagger JSON files.5 npmMIT