# auth.md

This is the Icons8 MCP server (`https://mcp.icons8.com`). It exposes MCP tools at `https://mcp.icons8.com/mcp/`. Six are for icons - `search_icons`, `list_categories`, `list_platforms`, `get_icon_png_url`, `get_icon_svg` and `get_icon_animation` - six for Ouch illustrations: `search_illustrations`, `list_illustrations_categories`, `list_illustrations_styles`, `get_illustration_svg`, `get_illustration_png_url` and `get_illustration_animation` - and `account_info`, which shows the caller's own account. Every tool call needs a credential: either an OAuth access token from the flow below, or a personal Icons8 API key pasted by hand (see the end of this document). A request with neither gets a `401` carrying `WWW-Authenticate`.

**The two sets do not treat the two credentials alike.** The icon tools accept either one. The illustration tools reach Icons8's Ouch API, which reads only an Icons8 sign-in token, which this server keeps current for you after the sign-in below: a hand-pasted key authenticates the call to this server but is anonymous to Ouch, so paid formats stay closed and the preview links in a search result come back watermarked. If you need either, sign in through the flow below rather than pasting a key.

## 1. Discover

The `401` on `https://mcp.icons8.com/mcp/` carries:

```
WWW-Authenticate: Bearer error="invalid_request", error_description="Authorization required", resource_metadata="https://mcp.icons8.com/.well-known/oauth-protected-resource/mcp"
```

Fetch the `resource_metadata` URL (also published at the conventional root path, `https://mcp.icons8.com/.well-known/oauth-protected-resource`, and both mirror the same document):

```json
{
  "resource": "https://mcp.icons8.com/mcp",
  "authorization_servers": ["https://mcp.icons8.com/"],
  "scopes_supported": ["icons8"],
  "bearer_methods_supported": ["header"]
}
```

`bearer_methods_supported: ["header"]` means the token goes in an `Authorization: Bearer <token>` header - the same header a hand-pasted personal key uses. Then fetch the authorization server's own metadata, at the one entry in `authorization_servers` above:

```
GET https://mcp.icons8.com/.well-known/oauth-authorization-server
```

```json
{
  "issuer": "https://mcp.icons8.com/",
  "authorization_endpoint": "https://mcp.icons8.com/authorize",
  "token_endpoint": "https://mcp.icons8.com/token",
  "registration_endpoint": "https://mcp.icons8.com/register",
  "revocation_endpoint": "https://mcp.icons8.com/revoke",
  "response_types_supported": ["code"],
  "code_challenge_methods_supported": ["S256"],
  "client_id_metadata_document_supported": true,
  "token_endpoint_auth_methods_supported": ["client_secret_post", "client_secret_basic", "none"],
  "grant_types_supported": ["authorization_code", "refresh_token", "urn:workos:agent-auth:grant-type:claim"],
  "scopes_supported": ["icons8"],
  "agent_auth": {
    "skill": "https://mcp.icons8.com/auth.md",
    "identity_endpoint": "https://mcp.icons8.com/agent/identity",
    "claim_endpoint": "https://mcp.icons8.com/agent/identity/claim",
    "register_uri": "https://mcp.icons8.com/agent/identity",
    "claim_uri": "https://mcp.icons8.com/agent/identity/claim",
    "identity_types_supported": ["service_auth", "identity_assertion"],
    "identity_assertion": {
      "assertion_types_supported": ["verified_email"],
      "credential_types_supported": ["access_token", "refresh_token"]
    },
    "credential_types_supported": ["access_token", "refresh_token"]
  }
}
```

This server is its own authorization server - `issuer` here matches the one entry in `authorization_servers` above, and there is nothing further to resolve.

## 2. Register

If your client publishes a Client ID Metadata Document, skip this step: use the document's https URL as `client_id` from here on, with no client secret. A document this server cannot use is answered only with "Client ID not found", so it must meet every rule below:

- its `client_id` equals the URL it is served from, character for character;
- the URL is https with a path, and its host resolves only to public addresses;
- the host answers 200 with at most 5 KB of JSON, without a redirect;
- it declares `"token_endpoint_auth_method": "none"` and carries no `client_secret`;
- `redirect_uris` is a non-empty list, each https, or http on `localhost`, `127.0.0.1` or `[::1]` - a loopback redirect matches on any port;
- `grant_types`, if present, includes `authorization_code`. Of the rest, only `refresh_token` is granted; any other grant is ignored.

Otherwise register your client once with Dynamic Client Registration ([RFC 7591](https://www.rfc-editor.org/rfc/rfc7591)):

```
POST https://mcp.icons8.com/register
Content-Type: application/json

{"client_name": "<your agent>", "redirect_uris": ["<your redirect URI>"]}
```

The response carries a `client_id` (and, for a confidential client, a `client_secret`) to use in the next step. No human is involved in this step. A body that is not a JSON object, an empty one included, gets `400` with `invalid_client_metadata`.

## 3. Authorize - a human signs in

Build the authorization URL with PKCE ([RFC 7636](https://www.rfc-editor.org/rfc/rfc7636)) and send the user's browser there - this step cannot be done headlessly, it is where the Icons8 account owner proves who they are:

```
GET https://mcp.icons8.com/authorize
  ?response_type=code
  &client_id=<from step 2, or your document URL>
  &redirect_uri=<your redirect URI>
  &scope=icons8
  &state=<opaque value you generate>
  &code_challenge=<S256 of a code_verifier you generate>
  &code_challenge_method=S256
```

The user lands on this server's own sign-in page and enters the email and password of their Icons8 account. On success, the browser is redirected back to `redirect_uri` with `code` and your `state`.

## 4. Exchange the code

```
POST https://mcp.icons8.com/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=<from step 3>&redirect_uri=<same URI>&client_id=<from step 2, or your document URL>&code_verifier=<from step 3>
```

```json
{
  "access_token": "mcp1_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "..."
}
```

`access_token` resolves, on this server, to the same personal Icons8 API key already used for manual auth (below) - it grants exactly what that Icons8 account's licence grants, nothing more. It expires in one hour.

## 5. Use the token

```
GET https://mcp.icons8.com/mcp/
Authorization: Bearer <access_token>
```

## 6. Refresh, and revoke

When `access_token` expires, exchange `refresh_token` for a new one without asking the user to sign in again:

```
POST https://mcp.icons8.com/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=<from step 4>&client_id=<from step 2, or your document URL>
```

To end a grant, `POST https://mcp.icons8.com/revoke` with `token=<access_token or refresh_token>` ([RFC 7009](https://www.rfc-editor.org/rfc/rfc7009)).

## Alternative: register an agent with a claim code (`service_auth`)

Use this when your agent has no browser redirect to receive a code, but a person is at hand who owns an Icons8 account and whose email you know. It is the `agent_auth` block of the authorization server metadata above. Two request shapes start the same ceremony, and both mean "the person confirms this email by signing in": `{"type": "service_auth", "login_hint": ...}` and `{"type": "identity_assertion", "assertion_type": "verified_email", "login_hint": ...}`. `identity_assertion` here is not an assertion you mint. `anonymous` answers `400 anonymous_not_enabled` (this server has no anonymous access) and an `identity_assertion` that carries an ID-JAG answers `400 issuer_not_enabled` (this server trusts no identity provider). You still need a `client_id` from step 2. `credential_types_supported` in the metadata lists what the claim returns: an `access_token` and a `refresh_token`.

**Step A - register.** Send the person's email:

```
POST https://mcp.icons8.com/agent/identity
Content-Type: application/json

{"type": "service_auth", "login_hint": "<the person's email>"}
```

(or `"type": "identity_assertion"` with `"assertion_type": "verified_email"`; the answer is the same, with `registration_type` echoing what you sent)

```json
{
  "registration_id": "reg_...",
  "registration_type": "service_auth",
  "claim_url": "https://mcp.icons8.com/agent/identity/claim",
  "claim_token": "clm_...",
  "claim_token_expires": "2026-10-20T12:00:00.000Z",
  "post_claim_scopes": ["icons8"],
  "claim": {
    "user_code": "123456",
    "expires_in": 600,
    "verification_uri": "https://mcp.icons8.com/oauth/login?req=...",
    "interval": 5
  }
}
```

`claim_token` is returned once and lives an hour: keep it in memory.

**Step B - hand off to the person.** Show them `verification_uri` and `user_code` in one message, for example: "Open this link, sign in, and enter this 6-digit code: 123456". The code goes into the page they reach after signing in, not back to you, and in the same browser they signed in with. They must sign in as the account whose email you sent as `login_hint`; another account cannot confirm. Five wrong codes end the registration.

**Step C - poll.** Every `interval` seconds, until the person confirms:

```
POST https://mcp.icons8.com/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn:workos:agent-auth:grant-type:claim&claim_token=<clm_...>&client_id=<from step 2, or your document URL>
```

While the person has not confirmed the answer is `400 authorization_pending`. If the code runs out (`400 expired_token`), ask for a fresh one and show it, then resume polling:

```
POST https://mcp.icons8.com/agent/identity/claim
Content-Type: application/json

{"claim_token": "<clm_...>", "email": "<the same login_hint>"}
```

The answer carries a new `claim_attempt` with the same fields as `claim`. `400 access_denied` means the person declined: stop polling, do not register again, and tell them. `400 invalid_grant` means the claim token is wrong, expired or already used: start again at step A.

When the person has confirmed, the poll returns the same token response as step 4 (`access_token`, `expires_in`, `refresh_token`), once. Use the access token as in step 5 and refresh and revoke it as in step 6. There is no signed identity assertion in the response and no JWT-bearer grant here: the refresh token does that job.

Errors at `/agent/identity` and `/agent/identity/claim` are JSON with `error` and `error_description`: `invalid_request`, `anonymous_not_enabled`, `issuer_not_enabled`, `invalid_claim_token`, `claimed_or_in_flight`.

## Alternative: a personal key, no registration at all

Paste a personal API key from the Icons8 account directly, with no registration and no expiry:

```
Authorization: Bearer <personal Icons8 API key>
```

This is the simplest path for a client that already holds one. It is unaffected by anything above.

## Troubleshooting

A `401` on a previously-working `access_token` means it expired or was revoked - retry step 6, or start over at step 3 if that also fails. During step 3, the sign-in page itself explains what went wrong to the human at the keyboard (wrong email or password, an account with no Icons8 password, an account without MCP API access, or a transient failure worth retrying) - an agent driving that step should relay the page's own message rather than guess at the cause.
