Connecting to the Beyond MCP Server

This guide explains how an MCP client (an AI agent such as Claude or ChatGPT) authenticates a user and establishes an authorized connection to the Beyond MCP server.

TL;DR

The MCP server uses standard OAuth 2.0. Your client discovers the authorization server from the MCP server's metadata, registers itself, runs the Authorization Code flow with PKCE so the user can log in and grant access, then calls the MCP tools with the resulting bearer token. Most MCP clients automate all of this once you point them at the server URL.

What you connect to

Item	Value
MCP server URL	https://neyoba.beyondpricing.com/mcp
Authorization server	https://developers.beyondpricing.com
Sign-in / consent page	https://v2.beyondpricing.com/oauth/authorize
Required scope	neyoba:ask

Client requirements:

• Public client: token endpoint authentication method none (no client secret).
• PKCE is required, using S256.
• Supported grants: authorization_code, refresh_token.

Endpoint reference

Purpose	Method	URL
Protected-resource metadata (RFC 9728)	GET	https://neyoba.beyondpricing.com/.well-known/oauth-protected-resource/mcp
Authorization-server metadata (RFC 8414)	GET	https://developers.beyondpricing.com/.well-known/oauth-authorization-server (see note)
Dynamic client registration (RFC 7591)	POST	https://developers.beyondpricing.com/o/register/
Authorization (sign-in / consent)	GET (browser)	https://v2.beyondpricing.com/oauth/authorize
Token / refresh	POST	https://developers.beyondpricing.com/o/token/
Revocation	POST	https://developers.beyondpricing.com/o/revoke/

You normally do not hardcode these. Discover them from the metadata documents in steps 1–2; the values above are shown so you know what to expect.

A note on discovering the authorization server (two paths)

There are two ways clients discover the authorization-server metadata, and they return two slightly different (but equivalent) documents:

• Spec-compliant clients (e.g. Claude) read the protected-resource metadata (step 1), follow its authorization_servers pointer to https://developers.beyondpricing.com, and fetch the authorization server's own metadata from https://developers.beyondpricing.com/.well-known/oauth-authorization-server. This is the path drawn in the diagram below.
• Clients that do not follow the authorization_servers pointer (e.g. ChatGPT) instead look for authorization-server metadata at the MCP server's own origin. For compatibility, the MCP server replicates that document at https://neyoba.beyondpricing.com/mcp/.well-known/oauth-authorization-server (and .../mcp/.well-known/openid-configuration, plus the origin-root variants). Step 2 below shows this replica.

Both documents advertise the same authorization, token, registration, and revocation endpoints, so either discovery path leads to the same flow. They differ only cosmetically: the replica's issuer is the MCP resource URL and it lists just the neyoba:ask scope, while the authorization server's own document uses its own host as issuer and may list additional scopes and grant types.

Flow

sequenceDiagram
    participant U as User
    participant C as MCP Client
    participant M as MCP Server
    participant A as Authorization Server
    participant V as Consent Page

    C->>M: POST /mcp without bearer token
    M-->>C: 401 WWW-Authenticate with resource_metadata
    C->>M: GET /.well-known/oauth-protected-resource/mcp
    M-->>C: authorization_servers and resource
    C->>A: GET /.well-known/oauth-authorization-server
    A-->>C: authorize, token, register, revoke endpoints
    C->>A: POST /o/register/
    A-->>C: client_id
    C->>V: GET /oauth/authorize with PKCE and resource via user browser
    U->>V: Log in and grant neyoba:ask
    V-->>C: Redirect to redirect_uri with authorization code
    C->>A: POST /o/token/ with code and code_verifier
    A-->>C: access_token and refresh_token
    C->>M: POST /mcp with Bearer access_token
    M-->>C: Tool result with response and thread_id

The diagram shows the spec-compliant discovery path: the client fetches authorization-server metadata from the authorization server (A) after following the authorization_servers pointer. Clients that read the replica at the MCP origin instead (see the note above) fetch it from M in step 2.

1. Discover the authorization server

Call the MCP endpoint with no credentials; the 401 response carries a WWW-Authenticate header whose resource_metadata parameter points at the exact protected-resource metadata URL. For this server that URL is https://neyoba.beyondpricing.com/.well-known/oauth-protected-resource/mcp (the resource path mcp is appended after the well-known name, per RFC 9728):

GET /.well-known/oauth-protected-resource/mcp HTTP/1.1
Host: neyoba.beyondpricing.com

The response advertises authorization_servers: ["https://developers.beyondpricing.com/"] and resource: "https://neyoba.beyondpricing.com/mcp".

2. Fetch authorization-server metadata

Spec-compliant clients fetch this from the authorization server they just discovered (https://developers.beyondpricing.com/.well-known/oauth-authorization-server). Clients that do not follow the authorization_servers pointer (e.g. ChatGPT) fetch the replica served at the MCP origin instead — shown here:

GET /mcp/.well-known/oauth-authorization-server HTTP/1.1
Host: neyoba.beyondpricing.com

{
  "issuer": "https://neyoba.beyondpricing.com/mcp",
  "authorization_endpoint": "https://v2.beyondpricing.com/oauth/authorize",
  "token_endpoint": "https://developers.beyondpricing.com/o/token/",
  "registration_endpoint": "https://developers.beyondpricing.com/o/register/",
  "revocation_endpoint": "https://developers.beyondpricing.com/o/revoke/",
  "scopes_supported": ["neyoba:ask"],
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "token_endpoint_auth_methods_supported": ["none"],
  "code_challenge_methods_supported": ["S256"]
}

(The authorization server's own document at developers.beyondpricing.com is equivalent for this flow but uses its own host as issuer and may list additional scopes, grant types, and token-endpoint auth methods.)

3. Register the client (Dynamic Client Registration, RFC 7591)

POST /o/register/ HTTP/1.1
Host: developers.beyondpricing.com
Content-Type: application/json

{
  "client_name": "Example Agent",
  "redirect_uris": ["https://client.example.com/oauth/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}

Returns a client_id. The client is public (token_endpoint_auth_method: none), so there is no client_secret; security comes from PKCE.

4. Authorize (Authorization Code + PKCE)

Generate a PKCE code_verifier and its S256 code_challenge, then send the user's browser to the sign-in / consent page:

https://v2.beyondpricing.com/oauth/authorize
  ?response_type=code
  &client_id=<client_id>
  &redirect_uri=https://client.example.com/oauth/callback
  &scope=neyoba:ask
  &state=<opaque-state>
  &code_challenge=<base64url-sha256>
  &code_challenge_method=S256
  &resource=https://neyoba.beyondpricing.com/mcp

The user logs in and grants the neyoba:ask scope. The browser is redirected to redirect_uri with ?code=<authorization_code>&state=<state>. Verify state matches what you sent.

5. Exchange the code for tokens

POST /o/token/ HTTP/1.1
Host: developers.beyondpricing.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=<authorization_code>
&redirect_uri=https://client.example.com/oauth/callback
&client_id=<client_id>
&code_verifier=<pkce_verifier>
&resource=https://neyoba.beyondpricing.com/mcp

Returns an access_token, a refresh_token, token_type: Bearer, expires_in, and scope. Treat the access token as opaque; do not attempt to decode it.

6. Call the MCP server

Send the bearer token with every MCP request:

POST /mcp HTTP/1.1
Host: neyoba.beyondpricing.com
Authorization: Bearer <access_token>
Content-Type: application/json

If a request returns 401 or 403, the token is expired or no longer valid: refresh it (step 7) or run the authorization flow again.

7. Refresh the access token

POST /o/token/ HTTP/1.1
Host: developers.beyondpricing.com
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=<refresh_token>
&client_id=<client_id>

8. Revoke (disconnect)

POST /o/revoke/ HTTP/1.1
Host: developers.beyondpricing.com
Content-Type: application/x-www-form-urlencoded

token=<access_or_refresh_token>
&client_id=<client_id>

Notes

• The MCP server never sees the user's login credentials. Sign-in and consent happen on the Beyond authorization pages.
• Access tokens are opaque. Do not parse or rely on their contents.
• Include resource=https://neyoba.beyondpricing.com/mcp on the authorization and token requests so the issued token is scoped to this MCP server.