open-climate.aiDocs

Integrate our MCP server into yours

This page shows queries.

This page is for software vendors only. It is the integration guide for a team that ships its own product: a carbon accounting tool, a procurement or ERP suite, a consultancy platform. You mount the open-climate.ai MCP server behind your own MCP server or agent, and your users map their lines to emission factors without leaving your product and without an account with us.

If you are not integrating a product, you want the matching page or factor search instead. If you want to know what we offer vendors commercially, read For software vendors.

What mounting means here#

Your backend holds one credential, a partner key. Every call it makes to our server names which of your users the call is for, in a header. Your users never see our server, never sign in to us, and never hold a credential of ours.

your user -> your product -> your MCP server -> https://api.open-climate.ai/mcp
                                                Authorization: Bearer ocai_live_...
                                                X-OCAI-Subject: <your id for that user>

That is one of two integration shapes, and the only one this page covers. The other is your users signing in to us themselves, in their own assistant, with OAuth. That route puts our brand, our sign-up and our approval queue in front of them, which is usually the opposite of what a vendor wants.

Before you start#

you need how you get it
A partner key, ocai_live_... issued as kind=partner Write to hello@open-climate.ai with your product, your expected volume and whether you want a sandbox key, a production key or both. We issue it; there is no self-service page.
A sandbox to build against https://dev.open-climate.ai/mcp. Same protocol, same key shape, separate data. Build there first.
One stable id per end user Your choice, and it is a decision worth making before the first call. See Name your users.

A user key looks the same and is not the same thing: it carries one account and no subject, so it can never act for anyone else. Only a partner key can.

The two headers#

Every call carries both.

header value
Authorization Bearer <your partner key>
X-OCAI-Subject Your own id for the end user this call is for

A partner key sent without X-OCAI-Subject is refused, and the refusal says so. That is deliberate: a partner key is never anonymous, because every job, file and result it creates is filed under a person.

Watch out. The partner key speaks for all of your users at once. Keep it on your server. It must never reach a browser, a mobile bundle, a client-side MCP config, or a prompt the model can read back to someone.

The transport is MCP streamable HTTP, and our server is stateless, so any request can land on any instance. You need no sticky sessions and no session affinity in front of it.

Name your users#

The subject is the identity half of the integration, and the choice has consequences.

subject you send what happens when to pick it
The user's email address Used as the account's address. If that person later signs in to open-climate.ai directly, it is the same account and the same history. You have the address and your terms let you forward it.
A stable opaque id, such as your internal user id or a UUID We keep the account under a placeholder address, distinct from every real one. Linking it to a direct sign-in later is a manual step. Forwarding an address is not appropriate for your product.

Two rules hold either way.

  • The subject must be stable for that user's lifetime in your system. Change it and you get a second account, with the earlier jobs left behind on the first.
  • A subject sees only what you created under it. One of your users cannot read another's jobs, and neither can another partner's users.

The account is created on the first call that names a new subject, and it is usable at once: partner traffic is approved on the strength of your key, so your users never sit in an approval queue. You vouch for them; that is what the key means.

What to put in front of your model#

Our server lists its own tools, so you do not maintain a copy of the list. Call get_emission_factor_mcp_server_info first: it takes no input, has no side effects, and proves that the key, the subject and the transport all work.

Two shapes work, and the second is the more common one.

  • Re-export our tools. Your MCP server forwards our tool list to your model, with the subject filled in per request. Leave out the tools declared for our in-chat widgets: they expect a host that renders them, and a headless model should not call them. The server marks them, so you can filter on the declaration rather than on a name list.
  • Wrap the sequence in one tool of your own. Your model sees map_this_file, and your server runs the steps. Most vendors end up here, because their model does not need to see six steps to answer one question.

The sequence, whichever shape you pick:

  1. upload_inline_rows for a handful of rows, or prepare_upload for a .csv, .xls or .xlsx file.
  2. plan_emission_factor_mapping to read the file's shape and propose the sheet, the header row and the columns.
  3. map_procurement_items_to_emission_factors to start the job. It returns a job_id.
  4. check_emission_factor_mapping_progress until the status is succeeded.
  5. get_emission_factor_mapping_result for the totals, then read_emission_factor_mapping_result_file for the matched rows.

A mapping job is asynchronous and a large file takes minutes, so poll from your server rather than holding a request open in front of your user.

Check the link before you build#

A call with no credential answers 401 and points at our OAuth metadata, which is a quick way to confirm you are talking to the right host:

curl -si -X POST https://dev.open-climate.ai/mcp | grep -i www-authenticate

www-authenticate: Bearer realm="ocai", resource_metadata="https://dev.open-climate.ai/.well-known/oauth-protected-resource/mcp"

To try the tools by hand before you write any code, point any MCP client that takes a JSON config at the sandbox with both headers:

{
  "mcpServers": {
    "open-climate-ai": {
      "type": "http",
      "url": "https://dev.open-climate.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${OCAI_PARTNER_KEY}",
        "X-OCAI-Subject": "you@your-product.example"
      }
    }
  }
}

Read the key from the environment rather than pasting it into the file, and use a subject you recognise: it creates a real account on our side on the first call.

What you owe your users#

Every matched row comes back with the library it came from, the factor's year, its unit and its licence. Pass those through to the user rather than showing a bare number: some libraries require attribution, a few forbid redistributing the factor value itself, and your product is where your user will look for that. Licences says what each one allows, and Cite a factor is the citation format we use.

  • API reference: the /v1 endpoints behind the tools, with a console that sends a real request from your browser using your own key. Use them directly if plain HTTP suits you better than MCP.
  • Licences and Cite a factor.
  • For software vendors: what the partnership looks like beyond the integration.