# auth.md

This document tells AI agents how to register and authenticate with Bloomiro MCP.

- Resource (MCP): https://mcp.bloomiro.com/mcp
- Authorization server: https://api.bloomiro.com
- App (human claim / docs): https://bloomiro.com

## 1. Discover

1. On a `401` from the MCP endpoint, read `WWW-Authenticate` for `resource_metadata="…"`, or fetch Protected Resource Metadata:

```http
GET https://bloomiro.com/.well-known/oauth-protected-resource
Accept: application/json
```

Required fields: `resource`, `authorization_servers`, `scopes_supported`, `bearer_methods_supported` (`header`).

The marketing-site PRM uses `resource` `https://bloomiro.com` so agents can discover auth from bloomiro.com. The live MCP endpoint is `https://mcp.bloomiro.com/mcp` (also advertised in the API catalog and OpenAPI).

2. Fetch Authorization Server metadata from each advertised issuer:

```http
GET https://api.bloomiro.com/.well-known/oauth-authorization-server
Accept: application/json
```

Read `issuer`, `authorization_endpoint`, `token_endpoint`, `registration_endpoint`, and the `agent_auth` block (`skill`, `register_uri`, anonymous registration).

## 2. Pick a method

| What you have | Method |
| --- | --- |
| Nothing yet (new MCP client) | Dynamic Client Registration at `agent_auth.register_uri`, then OAuth authorization code + PKCE |
| Human can open a browser | Send the user to the claim URI to connect a site and approve MCP |
| Project already connected | Use a project MCP API key from the dashboard (Bearer) |

Bloomiro does not implement ID-JAG (`urn:ietf:params:oauth:token-type:id-jag`) agent identity assertion yet. Prefer DCR + OAuth or an API key.

## 3. Register (anonymous / Dynamic Client Registration)

`agent_auth.register_uri` is the RFC 7591 registration endpoint:

```http
POST https://api.bloomiro.com/oauth/register
Content-Type: application/json

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

Then run the authorization code + PKCE flow against `authorization_endpoint` and `token_endpoint`. Request scopes `mcp:tools` and optionally `offline_access`.

Human-assisted claim (connect site / approve):

- Claim URI: https://bloomiro.com/mcp/authorize

## 4. Use the credential

```http
POST https://mcp.bloomiro.com/mcp
Authorization: Bearer <access_token_or_api_key>
Content-Type: application/json

{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}
```

When the access token expires, use the refresh token (if issued) or restart OAuth. API keys remain valid until revoked in the dashboard.

## 5. Docs

- Service doc (markdown): https://bloomiro.com/mcp.md
- Human setup: https://bloomiro.com/mcp
- OpenAPI: https://bloomiro.com/openapi.json
- API catalog: https://bloomiro.com/.well-known/api-catalog