Skip to main content
Glama

mc8yp

Version License Node Version

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 /mcp

Credentials

OS keyring (mc8yp creds add)

The caller's Authorization header

Tenant

The agent picks one with set-active-tenant

Fixed by the deployment

Extra tools

status, set-active-tenant

Optional sandbox shell (opt-in)

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

  1. Download the release zip from GitHub Releases.

  2. Upload it in Cumulocity Application Management and subscribe it.

  3. 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 remove

Users 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 mc8yp

Claude 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

/alarm/**

every method on /alarm and below

GET:/inventory/**

only GET on /inventory and below

DELETE:/inventory/**

only DELETE on /inventory and below

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

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 version

License

MIT

Available Tools

3 tools
codemodeCumulocity 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.

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

  2. 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 — check total too.

  3. 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:query or 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.

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

  5. Call the winner: await c8y.someMethod({ ...params, body }) (path/query/header parameters and body share 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.

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

    A4.2/5.0

    Scored across 3 tools

    Disambiguation4/5

    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.

    Naming Consistency3/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Production-grade MCP server that gives AI agents safe access to your local dev environment: filesystem, databases, processes, and OpenAPI specs.
      15
      40 npm
      4
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      MCP server that exposes RESTForge capabilities to AI agents, enabling them to set up, configure, generate code, and manage RESTForge projects through natural language.
      29
      44 npm
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An 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.
      4
      Apache 2.0