---
title: "Noiz Mail for Developers: Connecting Any MCP Client"
description: "The technical facts a developer needs to connect an MCP client or agent to Noiz Mail: endpoint, transport, OAuth 2.1 discovery, dynamic client registration, PKCE, tokens, scopes and the tool list."
url: "https://docs.noiz.ie/noiz-mail/noiz-mail-for-developers-connecting-any-mcp-client/"
section: "Noiz Mail"
categories:
  - "Applications > Noiz Mail > Reference"
tags:
  - "noiz-mail"
  - "mcp"
  - "oauth"
  - "developers"
  - "api"
last_reviewed: "4 November 2026, against the live Noiz Mail connector and its metadata documents"
---

# 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)](https://modelcontextprotocol.io/specification/latest/basic/authorization): the flow a client must implement.
- [RFC 9728, OAuth 2.0 Protected Resource Metadata](https://www.rfc-editor.org/rfc/rfc9728): how the client finds the authorization server.
- [RFC 8414, OAuth 2.0 Authorization Server Metadata](https://www.rfc-editor.org/rfc/rfc8414): the discovery document.
- [RFC 7591, OAuth 2.0 Dynamic Client Registration](https://www.rfc-editor.org/rfc/rfc7591): how a client registers itself.
- [RFC 7636, Proof Key for Code Exchange (PKCE)](https://www.rfc-editor.org/rfc/rfc7636): 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](/noiz-mail/noiz-mail-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.

---
Source: https://docs.noiz.ie/noiz-mail/noiz-mail-for-developers-connecting-any-mcp-client/