Connect over MCP

You connect an MCP client to https://mcp.open-climate.ai/mcp over streamable HTTP, sign in with OAuth or send an API key, then call get_emission_factor_mcp_server_info to check the link. The server's tools find the factors for one item, or map a whole file of purchase or activity lines to emission factors. To query factors from your own code, use the API or SQL.

Server URL and transport#

The transport is MCP streamable HTTP. The server is stateless, so any request can land on any instance. The marketing site at https://open-climate.ai serves no /mcp: use the mcp. or mcp.dev. host. A platform that mounts the server behind its own uses the address in Integrate our MCP instead.

Choose how you authenticate#

Every call needs a credential. Pick one of three.

A call with no credential answers 401 and points at the server's OAuth metadata:

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

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

That metadata names the authorization server (https://auth.open-climate.ai/realms/ocai) and the one scope, mcp:tools. An OAuth-capable client reads it, registers itself and opens the sign-in page. You do not configure any of it.

Note. A new account can read straight away. Mapping jobs start once the account is approved.

Add the server to ChatGPT or Claude.ai#

1. Open the connector settings. In ChatGPT: Settings, Connectors, Add a custom connector. In Claude.ai: Settings, Connectors, add a custom connector.
2. Paste https://mcp.open-climate.ai/mcp, or the sandbox URL.
3. Sign in on the page that opens, with email and password or Google.
4. On the consent screen, allow mcp:tools.

The tools appear in the connector once the window closes.

Watch out. If the tools show in the connector settings but never in a chat, and signing in again does not help, add the connector again under a URL variant such as https://mcp.open-climate.ai/mcp?v=2. The server answers it exactly like /mcp, and the client treats it as a new connector. Removing a connector and re-adding the same URL can bring back the broken one.

Configure a client with an API key#

A client that takes a JSON config, such as Claude Code, sends the key as a bearer header:

{
  "mcpServers": {
    "open-climate-ai": {
      "type": "http",
      "url": "https://mcp.open-climate.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${OCAI_API_TOKEN}"
      }
    }
  }
}

Set OCAI_API_TOKEN in your environment rather than pasting the key into the file.

With a partner key, add "X-OCAI-Subject": "<your user's id>" to headers. The subject is your own identifier for the end user. Each subject gets its own account on first call, and sees only the jobs made under it.

Make your first call#

Call get_emission_factor_mcp_server_info. It takes no input, has no side effects, and proves that auth and transport both work. The sandbox answered this on 2026-09-17:

{
  "name": "open-climate-ai",
  "package_version": "0.1.0",
  "started_at": "2026-09-17T12:29:35.268488Z",
  "transport": "http",
  "tool_names": ["check_emission_factor_mapping_progress", "create_lexicon", "..."]
}

transport should read http, and tool_names should list 15 tools. If your model sees 12, that is expected: three of them are declared for the in-chat widgets only, and hosts that honour that keep them away from the model. You do not need to know the names: the model reads them off the server. MCP tools lists them when you want to check one.

Ask about one item#

A one-item question, such as "a factor for a laptop" or "a hotel night in Spain", needs no file. The model calls search_emission_factors once per item and gets ranked factors back, each with its value, unit, region, library and a link to its page. That suits up to five items. For more, or for a ledger, map the file instead.

Map a file#

The usual sequence after the first call:

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

MCP tools gives every input and output.

Related#

• MCP tools
• Call the API
• API reference: the generated contract for the same /v2/ endpoints the tools call, with a console that sends a real request to the sandbox or production from your browser, using your own key.
• Quickstart: SQL