Skip to main content

Publishing a client metadata document

If you build an MCP client, no registration with Floxar is needed. Publish a Client ID Metadata Document and use its HTTPS URL as your client_id. Floxar fetches the document when your client first asks to connect, and the URL's domain is what people see when they are asked to allow the connection. The rules are those of the IETF client-ID-metadata-document draft, with a few narrowings described here.

For what a person sees and does when connecting, see Connecting an AI client.

How your client finds Floxar​

Each Floxar account has its own MCP URL, the account URL, of the form https://mcp.floxar.com/a/<account_id>. The person gives your client that URL. An unauthenticated request to it answers HTTP 401 with a WWW-Authenticate header pointing at the account's protected-resource metadata. That metadata names the authorization server, https://tokens.floxar.com, and the scopes Floxar offers. The authorization server's metadata says it supports client ID metadata documents and advertises no registration endpoint: Floxar does not offer dynamic client registration.

The URL​

  • HTTPS, with a path other than /.
  • No query, port, fragment or user info.
  • A DNS host name, not an IP address or localhost, written in lower-case ASCII exactly as it will be presented.
  • At most 512 characters.

The document​

  • JSON, served with a JSON content type, at most 5 KB, from the URL itself. A redirect is a failed fetch.
  • client_id equal to the URL.
  • client_name of at most 100 characters. People see it marked as your client's own claim.
  • One to ten redirect_uris, each either HTTPS on the same origin as the document, or an http loopback address (localhost, 127.0.0.1 or [::1], any port) for a native client.
  • A public client: token_endpoint_auth_method set to none, or none among the methods you list. Your client authenticates with PKCE alone.
  • grant_types including authorization_code, and refresh_token if you want to stay connected.
  • response_types including code.

Nothing else in the document is read or fetched; no logo is shown. A document that declares a client secret is refused.

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

Redirect URIs​

A redirect URI is matched exactly, as a string, with one exception: a native client's http loopback redirect matches whatever its port. localhost, 127.0.0.1 and [::1] never stand for one another, so register the one your client actually uses. Custom schemes are refused.

What gets a document refused​

  • A redirect URI on another host than the document's, or on a custom scheme.
  • A document over 5 KB.
  • A redirect instead of the document.
  • A shared-secret authentication method.
  • A web client with a loopback redirect.

A refused client sees Floxar's error page, with the reason, and is never redirected.

The request​

  • Ask for exactly one resource: the account URL the person entered. Floxar has no account picker; each account is its own URL.
  • Use PKCE with the S256 method.
  • Take your scopes from the protected-resource metadata: floxar.read, floxar.execute and floxar.author. Ask for at least one; a scope that names none of them is refused. A request with no scope at all is taken as asking for the three, without staying connected. Add offline_access to ask to stay connected.

Staying connected​

If your document's grant_types includes refresh_token, Floxar issues a refresh token whether or not you asked for offline_access. Refresh tokens rotate on every use. After 7 days without use, or 30 days in total, the person is asked to sign in again. A client whose document does not name the grant gets no refresh token and must send the person through sign-in again when its access expires.

Caching​

Your document's Cache-Control: max-age is honoured between 5 minutes and 24 hours, and taken as 1 hour when absent. A change to the document takes effect at the next fetch; connections already made stand. A connection is tied to your domain, not to the name the document declares, so it survives a change of name; the next consent shows the new name.

Errors and the consent page​

Until Floxar has reviewed your client, the consent page is headed by your document's domain, shows the full URL beneath it, marks the name you declare as your own claim, and tells the person that Floxar has not reviewed the client. Authorization errors for your client are shown on Floxar's error page and never redirected to you; the exception is access_denied, which returns to your client after the person chooses Deny, or after Floxar has refused the account and the person has read why.

Becoming a verified client​

Floxar keeps a list of clients it has verified: it reads the client's registration and connects it end to end. A verified client appears at consent under Floxar's own label, with no not-reviewed notice, and its errors are redirected to it as OAuth has it. Verification changes how your client is shown and served, not whether it can connect: any client that follows these rules can connect to an account that accepts it. An account admin can still deny any client, verified or not.

Last reviewed: 2026-09-30