Documentation

Updated

MCP

algizian meets the Model Context Protocol in two ways:

  1. A management MCP server lets an agent set up and run your tenants: the same operations as the management API, as tools.
  2. Every tenant is an authorization server that your own MCP server can use, so that Claude, ChatGPT and other connectors can sign their users in.

The management MCP server

  • Address: https://id.algizian.com/mcp
  • Transport: Streamable HTTP, stateless. Send JSON-RPC with POST; a GET answers 405.
  • Authentication: the same bearer tokens as the REST API (Authorization: Bearer ag_...). Without a valid token the server answers 401.

Connect an agent

With Claude Code:

claude mcp add --transport http algizian https://id.algizian.com/mcp \
  --header "Authorization: Bearer $ALGIZIAN_TOKEN"

Most MCP clients accept the same two values, the address and an Authorization header, in their server configuration.

Tools

The tools you see depend on the token. A read token sees only the read-only tools. A manage token adds the tools that change your tenant.

AreaTools
Identitywhoami
Tenant settingsget_tenant, update_tenant (display name, branding, enabled providers)
Logoset_logo (base64 PNG, JPEG or WebP up to 128 KiB; larger files go through the REST endpoint), delete_logo
Providerslist_providers, list_supported_providers, get_provider_setup, set_provider_credentials, remove_provider_credentials
Custom domainset_custom_domain, refresh_custom_domain, remove_custom_domain
Clientslist_clients, get_client, create_client, update_client, delete_client
Signing keyslist_keys, rotate_key
Userslist_users, get_user, create_user, block_user, unblock_user, unlink_identity, delete_user

Tools carry the standard hints: read-only tools are marked read-only, and tools that delete are marked destructive, so a client can ask for confirmation before running them. Errors come back as tool errors with the status, title and detail of the underlying API error.

A good first prompt for an agent with a manage token: add a public client with the redirect address https://app.example.com/callback, and show me the issuer and the client id.

Sign-in for your own MCP server

Remote MCP servers that need to know who is calling use OAuth. Claude and ChatGPT connectors do this by discovering the authorization server of your MCP server, registering themselves and sending the user through sign-in. A tenant provides everything that flow needs:

NeedWhere it is
Authorization server metadatahttps://<tenant>.algizian.com/.well-known/oauth-authorization-server (RFC 8414), also at /.well-known/openid-configuration
Dynamic client registrationregistration_endpoint in the metadata (RFC 7591)
Authorization code with PKCE S256/authorize and /token
Resource indicatorsthe resource parameter sets the audience of the access token (RFC 8707)
Issuer identificationthe iss parameter on the redirect back (RFC 9207)
Token validationthe tenant's /jwks.json

What your MCP server does:

  1. Answer unauthenticated requests with 401 and a WWW-Authenticate: Bearer resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource" header.
  2. Serve that protected resource metadata document (RFC 9728) from your own server, listing the tenant issuer, for example https://acme-games.algizian.com, under authorization_servers.
  3. Validate each access token against the tenant's key set: signature, iss, expiry and an aud equal to your MCP server's resource address.

The connector then reads the tenant's metadata, registers itself and runs the authorization code flow. The user signs in with Google, Microsoft or Apple on a screen with your branding and approves the connector once on a consent screen.

Dynamic client registration

POST https://<tenant>.algizian.com/register with the connector's redirect_uris (1 to 20) and an optional client_name creates a public client. Only token_endpoint_auth_method: "none" is accepted, so a connector uses PKCE instead of a secret. Registered clients are not first-party, so users see the consent screen for them.

curl -s -X POST https://acme-games.algizian.com/register \
  -H "Content-Type: application/json" \
  -d '{ "client_name": "Example connector", "redirect_uris": ["https://connector.example.com/oauth/callback"] }'

Connector redirect addresses are the ones the connector's vendor documents, for example the hosted callback of Claude (https://claude.ai/api/mcp/auth_callback) or the callback address of a ChatGPT connector. Dynamic registration is how they get registered; you do not add them by hand.

You can also pre-register a connector as an ordinary client with the management API, if you prefer a fixed client_id.