# Endufueler developer guide

> Endufueler MCP endpoints, OAuth discovery, preview-only sandbox and agent onboarding. Start with anonymous search and unsaved fueling previews.

Connect an MCP client to Endufueler to search endurance fuel products and calculate practical fueling previews. Begin without an account; connect with OAuth only for personal account actions.

## Start without a sales conversation or API key

When MCP is enabled, product search and unsaved plan previews are available anonymously. No payment details, API key generation or contact-sales form is required to try those tools. Usage limits apply. Reading account defaults, drafts or saved plans and saving a requested plan require a separate OAuth connection with the appropriate permissions.

The live Streamable HTTP MCP endpoint is https://endufueler.com/api/mcp. Use the integration setup page for client-specific connection URLs and deployment availability. This is an MCP service, not a general REST calculation API; discover its current tools and JSON input schemas rather than guessing endpoint names.

- [Client-specific setup and availability](https://endufueler.com/integrations)
- [Assistant usage guide](https://endufueler.com/integrations/guide)
- [Agent instructions](https://endufueler.com/llms.txt)

## Public HTTP contract and structured errors

Start with GET /api for a credentialless JSON index of the live MCP endpoint, sandbox endpoint, deployment availability and canonical OAuth metadata. GET /openapi.json publishes an OpenAPI 3.1 description of those existing HTTP resources and MCP transport messages. It includes typed tool argument/result schemas, unique operation IDs and the authorization-code security scheme.

Public initialize, tool discovery, product search and previews do not require authentication. Personal tool calls require the scopes listed in the contract and current MCP tool discovery. OpenAPI describes the HTTP transport; use tools/list as the authoritative runtime capability list, rather than treating a tool name as a separate REST route.

Unknown /api routes return an RFC 9457 application/problem+json error with the HTTP status, a stable code and a resolution hint. Unsupported methods on the public API index return a structured 405 with Allow. Existing OAuth errors, JSON-RPC protocol errors and browser API responses keep their established formats; a generic problem document is not substituted inside an MCP message.

```
curl -sS https://endufueler.com/api
curl -sS https://endufueler.com/openapi.json
```

- [Public API discovery JSON](https://endufueler.com/api)
- [OpenAPI specification](https://endufueler.com/openapi.json)

## OAuth 2.0 and discovery

The authorization server issuer is https://endufueler.com/api/auth. Its canonical RFC 8414 metadata document is /.well-known/oauth-authorization-server/api/auth. The root /.well-known/oauth-authorization-server URL redirects to that document for discoverability; it does not introduce a second issuer. Keep the returned issuer when configuring a client.

Use the authorization-code flow with PKCE S256 and the endpoints and capabilities in the metadata document. MCP protected-resource metadata is published at /.well-known/oauth-protected-resource/api/mcp. It identifies the authorization server for the live resource. Product search and public previews do not require account linking.

Personal reads require plans:read. A direct save requires both plans:write and plans:save and an explicit user request. Older connections may need a permission upgrade. Never ask a user to paste passwords or bearer tokens into a conversation, and do not treat an unsaved preview as a saved plan.

- [Authorization-server discovery](https://endufueler.com/.well-known/oauth-authorization-server)
- [Canonical OAuth metadata](https://endufueler.com/.well-known/oauth-authorization-server/api/auth)
- [MCP protected-resource metadata](https://endufueler.com/.well-known/oauth-protected-resource/api/mcp)

## Try the preview-only MCP sandbox

Use https://endufueler.com/api/mcp/sandbox to exercise real MCP initialization, tool discovery, product search and unsaved plan calculation when MCP is enabled. The sandbox uses the bundled catalog baseline rather than the live database catalog. Its server identity and result markers label the output as sandbox data.

The sandbox exposes only search_products and preview_plan. It cannot read an account, create OAuth grants or save plans. Do not send it account credentials. It shares the service's normal request, body, origin and usage protections; quota bookkeeping may be stored, but preview inputs and plans are not saved by the sandbox. It is not a test environment for personal OAuth or account writes.

Initialize the client, send notifications/initialized, then call tools/list with MCP-Protocol-Version set to the negotiated version. Follow each returned schema. Search products to obtain the sandbox catalogVersion and use it as expectedCatalogVersion when selecting product IDs. Sandbox catalog versions and results must not be passed to live saves.

```
curl -sS https://endufueler.com/api/mcp/sandbox \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"sandbox-example","version":"1.0"}}}'
```

- [Credentialless sandbox discovery JSON](https://endufueler.com/api/sandbox)

## A synthetic preview to test the contract

After initialization, call preview_plan with the synthetic arguments below. These example athlete and event values are illustrative, not a recommendation or facts about a user. For a real calculation, collect the required facts and data-use acknowledgement; do not infer consent, nutrition values or confirmed course support.

Explain targets, planned intake, warnings and assumptions separately. Keep unknown water or caffeine values unknown. A preview has not been saved. The assistant usage guide covers the complete workflow, account permissions and confirmation rules.

```
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "preview_plan",
    "arguments": {
      "raceInput": {
        "sport": "running",
        "event": {
          "distanceKm": 42.2,
          "expectedDurationMin": 240,
          "intensity": "steady",
          "temperatureBand": "warm"
        },
        "athlete": {
          "age": 35,
          "weightKg": 72,
          "fuelingExperience": "regular",
          "dataConsent": true
        },
        "fueling": {
          "mode": "recommendation",
          "wantsCaffeine": false
        }
      }
    }
  }
}
```

- [Read the complete assistant workflow](https://endufueler.com/integrations/guide)

## Support and service identity

Use the published contact page for integration questions or report catalog issues through the feedback page. The About page describes the planner and its limitations; the privacy policy explains data handling.

- [About Endufueler](https://endufueler.com/about)
- [Contact Endufueler](https://endufueler.com/contact)
- [Privacy policy](https://endufueler.com/privacy)
- [Markdown developer guide](https://endufueler.com/developers.md)