Operate MailGuardHQ from an AI client

Connecting

Three things: a credential, a running server, and a client pointed at it.

1. Get a token

You need a MailGuardHQ API token minted for the mcp audience. A free account is enough - sign up, verify your address, and mint one from your organisation. Tokens look like mgh_live_... in the live environment and mgh_test_... in test, and every one of them expires.

What free actually carries: one token at a time, a maximum lifetime of 30 days, and never dns:write - which an MCP token could not use anyway. That is enough to connect a client and drive the product; it is not enough to run a fleet on.

Scopes are chosen explicitly when you mint the token. There is no preset picker yet - you name the scopes you want, and a request for anything above what your role, your plan or the MCP audience permits is refused rather than quietly trimmed, so you find out at minting time instead of at the first call.

2. Run the server

One setting decides everything: which API it wraps. Nothing secret goes in a file - the credential travels on the request, from the client.

# the one setting that matters: which API this wraps
Api__BaseUrl=https://api.mailguardhq.com

dotnet run --project src/MailGuardHq.Mcp

Check it came up, and what it thinks it is. The readiness probe reports its own posture, including the honest state of audience verification, so an operator sees the gap in a probe rather than only in a document:

curl -s localhost:5000/health/ready

{"status":"ok","tools":20,"excluded":51,
 "specVersion":"v1","audienceVerification":"FormatOnly",
 "audienceVerifierOperational":false,"credentialRedaction":true,
 ...}

3. Point a client at it

The transport is streamable HTTP and the endpoint is /mcp. Configuration differs slightly between clients; the shape is always a URL and an Authorization header.

{
  "mcpServers": {
    "mailguardhq": {
      "type": "http",
      "url": "http://localhost:5000/mcp",
      "headers": {
        "Authorization": "Bearer mgh_live_..."
      }
    }
  }
}

The server is stateless - every request carries its own credential and nothing is remembered between them - so it scales sideways and a restart costs nobody a session.

1. Point your client at the server as above. On connect it asks for the tool list and gets all 20, each with its JSON schema, so the model knows what arguments are valid without being told.
2. Ask for a check in ordinary words - "check whether anyone can send email as yourcompany.com". The client picks the tool.
3. Read the findings. Each is a discrete result you can act on, not a paragraph of prose to interpret.

mgh_run_domain_check { "domain": "yourcompany.com" }

-> 13 findings, one per check, each with an id, a verdict of
   pass / warn / fail / not_applicable, and the evidence behind it.

mgh_run_domain_check accepts an Idempotency-Key, like every write on the API: repeat a call with the same key and the original response is replayed rather than the work being done twice.

The same check is available with no account and no client at all - the free domain check runs the identical thirteen checks in a browser.

There is no hosted endpoint, and no public release

Nothing is running at a URL you can point a client at. The server is not on GitHub, not in any MCP registry, and not installable from a package manager. Today it runs from source, against your own MailGuardHQ credential.

Public release - the repository, the licence and the registry listings - is tracked separately and is not done. Until it is, everything below describes a server you would run yourself.

Interactive sign-in is not available - clients paste a token

MailGuardHQ does not operate an OAuth authorization server. There is no /authorize, no /token and no client registration, so the OAuth 2.1 and PKCE flow an interactive client would normally use has nothing to talk to.

The server implements the half it can: it publishes RFC 9728 protected-resource metadata and challenges correctly. The authorization_servers list in that document is deliberately empty, because naming a server that does not exist sends every compliant client into a discovery loop that cannot end. So an interactive client asks you to paste a token, which works and is honest about what is available.

The server cannot verify a token was minted for it

The API mints tokens with an audience and applies the MCP ceiling when it does, so the restriction exists on the issuing side. What is missing is any way for this server to read the audience of a token it has been handed - there is no introspection endpoint - so it checks the token's format and no more, and logs a warning saying so on every start.

The consequence, stated plainly: a token minted for the ordinary API audience is accepted here. The verifier that closes this is written and tested against a stub, and starts working the day the API can answer the question.

Domain and organisation calls refuse an MCP token today

The API defaults every route to the API audience and opts individual routes in. The three check routes and five of the six token routes are opted in. The domain routes, the account route, the organisation and member routes and the bulk token-revoke route are not - so a correctly-minted MCP token is refused on them with wrong_audience.

That means "operate the product entirely through MCP" is not true today: checks and credential management work, domains do not. It is not worked around, because both available workarounds are worse - shipping tools that fail, or telling people to mint a token for the wrong audience, which is exactly what the audience mechanism exists to prevent.

A token minted over MCP does not hand back its secret

Minting and rotating work, and the response carries the token's id, prefix, scopes and expiry - but the secret is stripped before it reaches the model. You collect it from the web console.

A real narrowing, deliberately chosen: the alternative was a brand-new credential, at its maximum useful lifetime, deposited into a model's context and from there into any transcript, log or screenshot that context reaches.