Noiz Mail for Developers: Connecting Any MCP Client

Noiz Mail is a standard remote MCP server with OAuth 2.1 sign-in, so any MCP client that implements the current specification can connect without anything from us: no API key, no registration form. This page gives the facts a developer needs, with the standards they come from. It is for building your own agent or connecting a client we have not written a guide for; the guides for Claude, ChatGPT, Grok and Codex are in this section.

Last reviewed: 4 November 2026, against the live Noiz Mail connector and its metadata documents.

Official Documentation Reference

• MCP authorization (Model Context Protocol specification): the flow a client must implement.
• RFC 9728, OAuth 2.0 Protected Resource Metadata: how the client finds the authorization server.
• RFC 8414, OAuth 2.0 Authorization Server Metadata: the discovery document.
• RFC 7591, OAuth 2.0 Dynamic Client Registration: how a client registers itself.
• RFC 7636, Proof Key for Code Exchange (PKCE): required on every authorization.

Endpoints

What	Where
MCP endpoint	https://mcp.noiz.co.za/mail (streamable HTTP; POST for requests, bearer token in the Authorization header)
Protected resource metadata	https://mcp.noiz.co.za/.well-known/oauth-protected-resource/mail
Authorization server metadata	https://mcp.noiz.co.za/.well-known/oauth-authorization-server
Authorization	https://mcp.noiz.co.za/authorize
Token	https://mcp.noiz.co.za/token
Dynamic client registration	https://mcp.noiz.co.za/register
Manage page for end users	https://mcp.noiz.co.za/mail/manage

An unauthenticated request to the MCP endpoint answers 401 with a WWW-Authenticate header pointing at the protected resource metadata, as the specification requires, so a conforming client discovers everything else from there. Both metadata documents answer HEAD as well as GET.

The Sign-In Flow

1. The client fetches the protected resource metadata, then the authorization server metadata.
2. It registers itself at /register with its client_name and redirect URIs (at most 10, each at most 512 characters; JSON body at most 8 KB). Loopback redirect URIs are accepted for command-line clients. A registration that never completes a sign-in is deleted automatically.
3. It sends the user to /authorize with a PKCE challenge (S256 is the only method supported). The user sees the Noiz page Connect your mailbox and enters a mailbox address and password, with an optional list of further mailboxes. Passwords go only into that page.
4. The client exchanges the code at /token and receives an access token and a refresh token.

Item	Value
Grant types	authorization_code, refresh_token
PKCE	Required, S256
Scope	One scope, offline_access, advertised in both metadata documents. It gates nothing: a grant is always to the mailboxes signed in, and a refresh token is issued whether or not it is requested. Unknown scopes are ignored, never refused; a refresh cannot add scopes
Access token lifetime	1 hour
Refresh token lifetime	30 days from last use; rotates on every use
Connection lifetime	90 days from sign-in, then the user signs in again
Client identity	Any registered client. Nothing is tied to the client beyond its redirect URIs

Rate Limits on the Anonymous Endpoints

Endpoint	Allowed per client IP per 15 minutes
/register	300
/authorize (GET and POST together)	120
/token	1,200

Beyond these the answer is 429 with a Retry-After header. Sign-in attempts with a wrong password are limited separately: 5 per 15 minutes per client address and per mailbox. An IPv6 client is counted as its whole /64.

Tools

The ten tools, with parameters and limits, are in the tools reference. Points that matter when you write an agent:

• Every tool takes an optional mailbox; mail_search also takes mailbox="*". mail_accounts lists what the grant holds.
• Tool annotations mark each tool as read-only or not. mail_send is marked as needing confirmation and its description instructs the model to confirm with the user. Honour that in your client.
• Every read tool’s description states that message content is untrusted data. Keep that instruction in the model’s context; it is the only defence against prompt injection in mail that your client controls.
• A connection runs at most 4 calls at once; a fifth is told busy after 30 seconds. A call that cannot get a mail server session within 30 seconds is also told busy. Neither changes anything; retry later.
• A rejected password on a single-mailbox call revokes the grant (the next call gets 401; send the user to sign in again). In an all-mailboxes search a rejected mailbox is only listed in errors.

Writing a Client

Any MCP SDK that implements the current authorization specification works, with no Noiz-specific code: point its streamable HTTP client at https://mcp.noiz.co.za/mail with an OAuth provider that handles discovery, registration and PKCE. Test from a terminal first with Claude Code or Codex, which use the same discovery, so a problem that appears only in your client is in your client.

Your Own Mail Server

Noiz Mail also serves client mail servers that we manage. If we look after your mail server, your staff’s mailboxes can sign in the same way; ask us and we will switch it on.