Skip to main content

Building solutions with AI via the MCP server

OctoMesh ships an MCP server, a Model Context Protocol endpoint that lets AI assistants such as Claude Code or Claude Desktop work with your tenant through typed tools: discover the data model, query entities and time series, inspect pipelines and, if your permissions allow it, change things. In this tutorial you connect an assistant, let it explore the energy data from tutorial 3 and have it build a small evaluation for you.

Time: about 45 minutes.

How it works​

The MCP server has no data and no permissions of its own. Every tool call runs with your access token against the same services the Studio and octo-cli use, so the assistant can do exactly what you can do, and nothing more.

Step 1: Connect your AI client​

The MCP endpoint of an installation is https://mcp.<your-domain>/mcp. It serves all tenants; the tenant is chosen when you log in and can be passed per tool call.

Claude Code:

claude mcp add --transport http --scope user octomesh https://mcp.<your-domain>/mcp

Then run /mcp inside Claude Code and select octomesh.

Claude Desktop (claude_desktop_config.json, restart the app afterwards):

{
  "mcpServers": {
    "octomesh": {
      "type": "http",
      "url": "https://mcp.<your-domain>/mcp"
    }
  }
}

Other clients: any client that supports the streamable HTTP transport and OAuth authorization for MCP servers works the same way.

Step 2: Authenticate​

Spec-compliant clients authenticate on their own:

  1. The first request without a token is answered with 401 and a pointer to the server's protected resource metadata (https://mcp.<your-domain>/.well-known/oauth-protected-resource), which names the identity service.
  2. The client registers itself at the identity service (dynamic client registration; the client appears as octo-dcr-...) and opens a browser.
  3. You enter your e-mail address, pick your tenant and log in as usual.
  4. The client receives a token with the scopes openid profile email role octo_api offline_access and refreshes it automatically.

Check the connection by asking:

Who am I logged in as, and which tenant am I working in?

The assistant calls whoami and shows your user, roles and tenant. If your client cannot do the browser login, the server offers a device-code login through the authenticate tool; see MCP getting started.

Step 3: Explore the data model​

Ask in plain language. The assistant chooses the tools; the names in brackets show what typically happens.

Which Construction Kit models are installed in my tenant? (get_available_models)

Find the types related to metering points and show me the schema of EnergyCommunity/Consumer. (search_types, get_type_schema)

Which archives exist for Basic.Energy/EnergyMeasurement, and for which period do they hold data? (get_available_archive_paths, get_archive_coverage)

Compare the answers with what you saw in the Studio in tutorial 1.

Step 4: Query data​

List five consumers with their metering point number and partition factor. (query_entities)

For the consumer with metering point number <number>, which measurement anchors does it have? (navigate_associations)

Sum the raw energy measurements of yesterday per OBIS code. (query_stream_data_grouping)

Using the monthly rollup, compute the coverage ratio and the surplus ratio of the community for each of the last six months.

The last prompt needs several steps: finding the anchors per register, querying the rollup and dividing. Watch how the assistant plans them, and check its result against the numbers from tutorial 3.

Make the assistant show its work

Ask the assistant to show the tool calls and parameters it used, or to turn its steps into a GraphQL query or a script. That makes a result reproducible and lets you verify it without the assistant.

Step 5: From exploration to a small solution​

Once a question is answered, let the assistant turn it into something you can keep:

Write a Python script that computes the monthly coverage ratio and surplus ratio of my energy community through the GraphQL API, with the token from an environment variable. Use the queries you just ran.

Build a small web page that shows the daily coverage ratio of the last 30 days as a chart, reading the data through GraphQL.

For larger web applications the MCP server also offers scaffolding tools for OctoMesh custom apps (get_custom_app_template_manifest, plan_custom_app_scaffold, apply_custom_app_scaffold) and can export the GraphQL schema of your tenant for code generation (export_runtime_graphql_sdl). The generated code talks to the regular APIs, so everything in tutorial 2 applies, in particular checking the errors array of GraphQL responses.

Security boundaries​

  • Your token, your rights. The server forwards your identity. If you have write roles in a tenant, the assistant can write there too. For exploration, work with an account or a tenant where you only have read roles, or review every write the assistant proposes.
  • Tenant isolation. A token is bound to one tenant. Calls for another tenant only work if your user has been granted access there; the server then exchanges the token, with the roles you hold in that tenant.
  • Destructive operations need confirmation. Deleting, uninstalling or rolling back requires an explicit confirm: true parameter. Without it the tool refuses, and a well-behaved assistant asks you first. Keep your client's tool-approval prompts switched on for write tools.
  • Risk levels. Every tool is classified as low, medium or high risk (get_tool_risk_metadata). Clients and wrappers can use this to require approval for high-risk calls.
  • Secrets. Do not paste tokens, passwords or client secrets into the chat. Generic entity queries can return every attribute of an entity, including credentials on configuration entities, if no attribute list is given; ask for the specific attributes you need.
  • Verify. An assistant can misread a model or pick the wrong archive. Check important numbers with a query of your own.

Reference​

Next: Bringing your own data via pipeline endpoints.