Build a custom agent connection to the VentES MCP server

Discover the resource and authorization server

Use the resource URL exactly as shown. An unauthenticated MCP request returns a Bearer challenge pointing to protected-resource metadata. Discover the authorization server from that document rather than treating an application’s first-party SSO secret as an agent credential.

MCP resource
https://ssdashapi.ventes.group/mcp

Protected resource metadata
https://ssdashapi.ventes.group/.well-known/oauth-protected-resource/mcp

Authorization server metadata
https://ssdashapi.ventes.group/.well-known/oauth-authorization-server

Register and start authorization

Use a standard OAuth-capable MCP SDK where possible. The metadata advertises /oauth/register for dynamic public-client registration, token endpoint authentication method none and S256 PKCE. Registered callbacks must use HTTPS or native HTTP loopback. Client metadata URL documents are not fetched. Use the scopes actually returned by the token response; the human may authorize a subset of those requested.

1. Register a client_name and redirect_uris, using the public-client method none.
2. Generate a fresh PKCE verifier and its S256 challenge, plus a state value you will validate on callback.
3. Open the discovered authorization endpoint with response_type=code, client_id, the registered redirect_uri, code_challenge_method=S256, code_challenge, state, requested scope and resource=https://ssdashapi.ventes.group/mcp.
4. Let the human select a business and narrower capabilities in VentES.
5. Validate state and issuer on callback, then exchange the code with client_id, redirect_uri, resource and code_verifier at the token endpoint.

Call MCP with the issued bearer token

Send Authorization: Bearer with the access token to the resource URL. Initialize the MCP session and use tools/list before selecting a capability. The gateway negotiates MCP 2025-06-18 and also accepts 2025-03-26. It responds with JSON over Streamable HTTP; authenticated GET returns 405 because no unsolicited SSE stream is offered.

• Respect the input schema returned for each tool.
• Treat the tool list as the available capability set for the current token.
• Keep authorization failures separate from empty business results.
• Hosted browser clients may need an explicitly reviewed Origin configuration.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "ventes.business_context",
    "arguments": {}
  }
}

Handle proposed writes and results

Write tools return an action_id and approval_url. Surface that URL for the human, then retrieve the recorded result through ventes.action_status using the same connection. There is no agent confirmation tool.

For retried write proposals, send params._meta["ventes/idempotencyKey"] with a stable unique key of 1–128 characters. Reusing that key with the same arguments returns the original proposal; different arguments are rejected. Preserve action IDs and inspect failed or uncertain results before considering another write.

{
  "name": "ventes.action_status",
  "arguments": { "action_id": "<returned-action-id>" }
}

• Human approval behavior

Rotate, revoke and reconnect

Access tokens last 15 minutes. Use the rotating refresh token for renewal and replace the stored token pair atomically. The refresh family has a 30-day absolute lifetime; replay can revoke it. Use the advertised revocation endpoint or let the human revoke centrally. Reauthorize when access expires or the user wants a new business or permission selection.

• Troubleshooting
• Contact VentES about client acceptance