Connect Your AI to EcoSemantic¶

EcoSemantic is an MCP Server using Streamable HTTP transport. This means any MCP-compatible AI client can connect to access LCA tools and Ecoinvent data.

Server URL: https://mcp.ecosemantic.com/mcp

Recommended: Claude.ai (Web)¶

Claude.ai uses Connectors to connect to remote MCP servers. This is the easiest setup—no configuration files needed.

Plan Requirements

Custom connectors require Claude Pro, Max, Team, or Enterprise plan.

Step 1: Add the Connector¶

Go to claude.ai/settings/connectors
Scroll to the bottom and click "Add custom connector"
Enter the URL: https://mcp.ecosemantic.com/mcp
Click "Add"

Step 2: Connect & Authenticate¶

Open a new chat on Claude.ai
Click the "Search and tools" button (bottom left of chat)
Find EcoSemantic in the list
Click "Connect" to start authentication
You'll be redirected to EcoSemantic to authorize access
After authorizing, you'll return to Claude

Step 3: Enable Tools¶

After connecting:

Click "Search and tools" again
You'll see EcoSemantic's tools listed
Toggle on the tools you want Claude to use
Start chatting!

Test with:

Search for electricity production activities in Ecoinvent

Why Claude.ai Connectors is Recommended

No config files to edit
Automatic OAuth authentication
Works on web, desktop app, and mobile
Easiest setup (under 2 minutes)

Other Clients¶

Choose your AI client:

Cursor (OAuth)Claude DesktopWindsurfVS CodeClaude Code (CLI)

Cursor 1.0+ supports OAuth natively for remote MCP servers.

Simple Setup (OAuth - Recommended):

Edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "EcoSemantic": {
      "url": "https://mcp.ecosemantic.com/mcp"
    }
  }
}

When you first use the server, Cursor will automatically:

Detect OAuth is required
Open your browser for authentication
Complete the OAuth flow with EcoSemantic
Store tokens securely

Alternative: API Token

If OAuth doesn't work, use an API token:

{
  "mcpServers": {
    "EcoSemantic": {
      "url": "https://mcp.ecosemantic.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}

Claude Desktop requires mcp-remote to connect to remote servers with OAuth.

With OAuth (Recommended):

Edit your config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "EcoSemantic": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.ecosemantic.com/mcp"
      ]
    }
  }
}

On first use, mcp-remote will open your browser for OAuth authentication.

With API Token:

{
  "mcpServers": {
    "EcoSemantic": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.ecosemantic.com/mcp",
        "--header",
        "Authorization:Bearer YOUR_API_TOKEN"
      ]
    }
  }
}

Prerequisites

Claude Desktop (version 0.7.0+)
Node.js installed (for npx)

Windsurf supports MCP via mcp-remote for OAuth.

With OAuth (Recommended):

Open Settings (Cmd/Ctrl + ,) → MCP Servers:

{
  "mcpServers": {
    "EcoSemantic": {
      "command": "npx",
      "args": [
        "mcp-remote", 
        "https://mcp.ecosemantic.com/mcp"
      ]
    }
  }
}

With API Token:

{
  "mcpServers": {
    "EcoSemantic": {
      "command": "npx",
      "args": [
        "mcp-remote", 
        "https://mcp.ecosemantic.com/mcp",
        "--header",
        "Authorization:Bearer YOUR_API_TOKEN"
      ]
    }
  }
}

Use the MCP extension with mcp-remote for OAuth support.

With OAuth (Recommended):

Install MCP Extension from marketplace
Configure in settings:

{
  "mcpServers": {
    "EcoSemantic": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.ecosemantic.com/mcp"
      ]
    }
  }
}

With API Token:

{
  "mcpServers": {
    "EcoSemantic": {
      "serverUrl": "https://mcp.ecosemantic.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}

Claude Code supports both OAuth and API tokens.

With OAuth:

claude mcp add --transport http EcoSemantic https://mcp.ecosemantic.com/mcp

Then run /mcp in a session to authenticate via browser.

With API Token:

claude mcp add EcoSemantic \
  --transport http \
  --header "Authorization:Bearer YOUR_API_TOKEN" \
  https://mcp.ecosemantic.com/mcp

OAuth vs API Token¶

Method	Pros	Cons
OAuth	Automatic token refresh, more secure, no token management	Requires browser for initial auth
API Token	Simple setup, works offline	Manual token management, less secure

Recommendation: Use OAuth when available. It's more secure and handles token refresh automatically.

Getting Your API Token¶

If you need an API token (for clients without OAuth or for automation):

Log in at ecosemantic.com/dashboard
Go to Settings → API Tokens
Click "Generate New Token"
Copy immediately (shown only once)

Keep Your Token Secure

API tokens provide full access to your account. Never commit them to git or share publicly.

Verify Connection¶

After setup, test with this prompt:

Search for electricity production activities in Ecoinvent

If your AI uses search_activities and returns results, you're connected!

Managing Your Connection¶

Claude.ai: Edit or Remove Connector¶

Go to claude.ai/settings/connectors
Find EcoSemantic in the list
Click the three dots menu
Choose Edit or Remove

Revoke OAuth Access¶

To revoke any client's access to your EcoSemantic account:

Go to your EcoSemantic Dashboard
Navigate to Settings → Connected Apps
Find the app and click Revoke

Troubleshooting¶

Problem	Solution
"Connector not showing" (Claude.ai)	Refresh page, verify Pro/Max/Team/Enterprise plan
"OAuth flow doesn't start"	Check browser popup blocker, try different browser
"mcp-remote not found"	Install Node.js, run `npm install -g mcp-remote`
"Authentication failed"	Try disconnecting and reconnecting, regenerate API token
"Tools not appearing"	Click "Search and tools" and enable them manually

Transport Details¶

EcoSemantic uses Streamable HTTP (not SSE):

Endpoint: https://mcp.ecosemantic.com/mcp
Protocol: MCP 2025-06-18
Auth: OAuth 2.1 (recommended) or Bearer token

The mcp-remote package handles both OAuth and transport bridging for clients that don't natively support Streamable HTTP.