# Agnost AI auth.md

Agent-readable authentication and OAuth client registration instructions for the hosted Agnost AI MCP service.

## 1. Discover the OAuth service

- Protected resource: `https://mcp.agnost.ai/`
- MCP endpoint: `https://mcp.agnost.ai/mcp`
- Site-root Protected Resource Metadata alias: `https://agnost.ai/.well-known/oauth-protected-resource`
- Site-root Authorization Server Metadata alias: `https://agnost.ai/.well-known/oauth-authorization-server`
- Protected Resource Metadata: `https://mcp.agnost.ai/.well-known/oauth-protected-resource`
- Authorization Server Metadata: `https://mcp.agnost.ai/.well-known/oauth-authorization-server`
- Authorization server and issuer: `https://mcp.agnost.ai/`
- Supported scope: `agnost`

The protected-resource metadata advertises bearer tokens in the HTTP `Authorization` header. The authorization-server metadata is the source of truth for current endpoints and capabilities.

## 2. Choose the registration method

Agnost supports OAuth Dynamic Client Registration followed by user authorization. The user signs in with Google and grants access through the Agnost authorization flow.

- Identity type: `user_authorization`
- Grant types: `authorization_code`, `refresh_token`
- Response type: `code`
- PKCE method: `S256`
- Credential types: `access_token`, `refresh_token`
- Token transport: `Authorization: Bearer <access_token>`

Agnost does not advertise anonymous, verified-email, or ID-JAG registration. Do not attempt those flows unless the discovery metadata changes.

## 3. Read the agent registration metadata

The authorization-server metadata includes this registration description:

```json
{
  "agent_auth": {
    "skill": "https://agnost.ai/auth.md",
    "register_uri": "https://mcp.agnost.ai/register",
    "authorization_uri": "https://mcp.agnost.ai/authorize",
    "identity_types_supported": ["user_authorization"],
    "credential_types_supported": ["access_token", "refresh_token"],
    "user_authorization": {
      "grant_types_supported": ["authorization_code", "refresh_token"],
      "response_types_supported": ["code"],
      "code_challenge_methods_supported": ["S256"],
      "credential_types_supported": ["access_token", "refresh_token"]
    }
  }
}
```

## 4. Register an OAuth client

Send OAuth Dynamic Client Registration metadata to `register_uri`. Registration creates a client identifier, not an Agnost user account.

```http
POST /register HTTP/1.1
Host: mcp.agnost.ai
Content-Type: application/json

{
  "client_name": "Example Agent",
  "redirect_uris": ["http://127.0.0.1:3210/callback"],
  "token_endpoint_auth_method": "none",
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "scope": "agnost"
}
```

Use a loopback redirect URI, a private-use application URI, or another redirect URI explicitly supported by Agnost. Do not pass arbitrary remote callback hosts.

Passive scanners must not call `POST /register`. Read the public discovery documents instead.

## 5. Authorize with PKCE

Open `authorization_uri` in the user's browser with the registered `client_id`, exact `redirect_uri`, `response_type=code`, `scope=agnost`, a random `state`, and an S256 `code_challenge`. The user completes Google sign-in and Agnost redirects the authorization code to the registered callback.

Exchange the code at `https://mcp.agnost.ai/token` using the original PKCE verifier. Refresh tokens may be exchanged at the same endpoint with `grant_type=refresh_token`.

## 6. Use the credential

Send the access token to the protected MCP service in the request header:

```http
Authorization: Bearer <access_token>
```

Use `https://mcp.agnost.ai/mcp` for streamable-HTTP MCP requests. Organization access and permissions are derived from the signed-in Agnost account. Never place access tokens in URLs, logs, or client configuration files.

## 7. Errors and credential lifecycle

- Retry authorization from the beginning if the user denies access, state validation fails, or a code expires.
- Re-register if the client identifier is rejected or its redirect configuration must change.
- Stop using a credential after an authentication failure and ask the user to authorize again.
- Agnost does not currently advertise an OAuth revocation endpoint. Do not invent or probe one.

Human-readable integration documentation: `https://docs.agnost.ai/agnost-mcp-server`