Client Integration

This page explains how to connect an application or AI client to the Etalasse MCP server over the HTTP transport.

Requirements

the Etalasse MCP endpoint URL for your environment, for example https://mcp.etalasse.com
valid authentication — an OAuth session (see OAuth Setup), or a bearer token provided for server-to-server integrations
a client that can send JSON-RPC 2.0 requests over HTTP POST, or a ready-made MCP client

Endpoints

Endpoint	Purpose
`GET /health`	Server health check, no authentication required.
`POST /mcp`	The main MCP endpoint for `initialize`, `tools/list`, and `tools/call`.

Server behavior notes:

every response includes an x-request-id header for tracing
CORS is restricted to an allowlist of origins
per-IP rate limiting is applied to HTTP requests

MCP client configuration

For AI clients that support remote MCP servers (such as Claude Code or Codex), simply register the HTTP endpoint. Minimal example:

{
  "mcpServers": {
    "etalasse": {
      "type": "http",
      "url": "https://mcp.etalasse.com/mcp"
    }
  }
}

The client will discover the OAuth metadata automatically and open the sign-in flow on first use.

Integration flow from an application

If you call MCP directly from your own application, the recommended flow is:

Call GET /health at startup.
Send initialize.
Send tools/list and cache the tool catalog if needed.
Use tools/call for each action.
Surface tool failures directly — Etalasse API errors are already normalized by the MCP server.

The five steps on the left; step 4 is the tools/call request: (1) the Authorization and MCP-Protocol-Version headers, (2) the JSON-RPC body, (3) the response with x-request-id.

1. Health check

curl https://mcp.etalasse.com/health

Expected response shape:

{
  "ok": true,
  "service": "etalasse-mcp",
  "transport": "http",
  "mcp_path": "/mcp"
}

2. Initialize

curl -X POST https://mcp.etalasse.com/mcp \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2026-07-28",
      "capabilities": {},
      "clientInfo": { "name": "my-app", "version": "1.0.0" }
    }
  }'

3. List tools

curl -X POST https://mcp.etalasse.com/mcp \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list",
    "params": {}
  }'

4. Call a tool

Example public shop lookup:

curl -X POST https://mcp.etalasse.com/mcp \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "shop.get_by_username",
      "arguments": { "username": "demo-shop" }
    }
  }'

Use system.ping as your first tool call to verify the end-to-end connection before calling business tools.

Error handling

Handle these codes centrally in your client:

401 — authentication is missing or expired; repeat the OAuth flow or refresh the token
403 — the session is not allowed to run that tool
429 — rate limited; retry with backoff
tool-level errors — returned inside the tools/call result; messages are already normalized from Etalasse API responses

Include the x-request-id value when reporting issues to speed up tracing.

Protocol version note

If your client uses a different MCP protocol revision, update both consistently:

the MCP-Protocol-Version header
params.protocolVersion in initialize

Requirements​

Endpoints​

MCP client configuration​

Integration flow from an application​

1. Health check​

2. Initialize​

3. List tools​

4. Call a tool​

Error handling​

Protocol version note​

Related pages​