Skip to content
nofeb

Product / Agents and MCP

Mailboxes an agent can open for itself

nofeb is built for software that reads and writes mail on its own. An agent can create its organization, its inboxes and its key in one call, and every operation it needs is both a REST endpoint and an MCP tool that behaves identically.

An agent can sign itself up

One unauthenticated call creates an organization, a first inbox and an API key. The agent names a human sponsor. Until that person verifies by email, the organization may only reply to people who wrote to it first, in the same thread, so a fresh signup cannot be used to send cold mail.

That is enough for the most common first job, receiving a verification code for a sign-up, with no human in the loop until the agent needs to write to someone new.

Agent self-signup
curl -X POST https://API_HOST/v1/agent/signup \
  -H 'content-type: application/json' \
  -d '{"name": "research agent", "sponsor_email": "owner@example.com"}'

Tools generated from the API, not written beside it

The MCP server and the REST API are generated from one operation table. A tool call is dispatched through the same router as the HTTP request, so a tool cannot validate, authorize or fail differently from its endpoint, and a parity test fails the engine build if the two drift.

117 tools, served over streamable HTTP and named for the job rather than the endpoint: get_thread_context returns a whole thread ready for a model, set_thread_state records where the work stands, wait_for_email blocks until the code arrives, search_email and query_threads find work across inboxes, and find_availability and book_meeting schedule from the inbox's own calendar.

  • whoami
  • list_pods
  • create_pod
  • list_inboxes
  • create_inbox
  • get_inbox
  • delete_inbox
  • list_messages
  • wait_for_email
  • get_message
  • update_message
  • send_message
  • reply_to_message
  • forward_message
  • get_send_status
  • decide_send
  • get_thread_context
  • get_message_metadata
  • set_message_metadata
  • get_thread_state
  • set_thread_state
  • get_inbox_metadata
  • set_inbox_metadata
  • list_metadata_schema
  • declare_metadata_key
  • list_events
  • create_webhook
  • list_domains
  • create_domain
  • get_domain
  • verify_domain
  • get_dns_setup
  • create_hook
  • test_hook
  • list_held_sends
  • list_policy_entries
  • add_policy_entry
  • remove_policy_entry
  • check_recipients
  • get_policy_settings
  • set_policy_settings
  • get_send_caps
  • query_audit_log
  • list_rules
  • create_rule
  • update_rule
  • delete_rule
  • test_rules
  • import_sieve
  • export_sieve
  • list_quarantine
  • release_message
  • delete_quarantined_message
  • get_message_safety
  • scan_text
  • decide
  • list_decision_schemas
  • create_decision_schema
  • delete_decision_schema
  • relabel_decision
  • extract_message
  • list_extraction_schemas
  • create_extraction_schema
  • search_email
  • query_threads
  • find_inboxes
  • get_hooks_wit
  • upload_hook_module
  • get_hook_module
  • update_hook_module
  • list_calendars
  • get_calendar_settings
  • update_calendar_settings
  • list_calendar_events
  • create_calendar_event
  • get_calendar_event
  • update_calendar_event
  • delete_calendar_event
  • respond_to_invite
  • find_availability
  • get_free_busy
  • book_meeting
  • create_draft
  • list_drafts
  • get_draft
  • update_draft
  • delete_draft
  • send_draft
  • get_thread_driver
  • set_thread_driver
  • create_forwarding_address
  • list_forwarding_addresses
  • get_forwarding_address
  • update_forwarding_address
  • rotate_forwarding_address
  • revoke_forwarding_address
  • start_export
  • get_export
  • list_retention_policies
  • create_retention_policy
  • dry_run_retention
  • get_sending_status
  • get_domain_warmup
  • get_ai_disclosure
  • list_agents
  • create_agent
  • get_agent
  • revoke_agent
  • verify_agent_signature
  • get_mail_client_settings
  • list_federated_issuers
  • create_federated_issuer
  • delete_federated_issuer
  • list_federation_bindings
  • create_federation_binding
  • delete_federation_binding
  • test_federated_token

Wait for the code, not a polling loop

wait_for_email long-polls an inbox for up to a minute and returns as soon as a message matches the sender, subject or has_otp filter. Every message arrives with its one-time codes and classified links already extracted, so the agent reads a field instead of parsing HTML.

Inboxes can be given a time to live. A browser session, a test run or a single sign-up gets its own address, and the inbox removes itself, with an event, when it expires.

Wait for a sign-up code
GET /v1/inboxes/{inbox_id}/wait?has_otp=true&timeout=60

{ "message": { "id": "e3KX9Q", "subject": "Your code", "otps": [{ "code": "482913", "source": "body" }], ... } }

Connect with a key

Any MCP client that supports remote servers over streamable HTTP can connect with an API key sent as a bearer token. Scope the key to one inbox and the agent cannot see or send from any other.

The TypeScript and Python SDKs are generated from the same OpenAPI document: @nofeb/sdk for Node, Deno, Bun and edge runtimes, and nofeb for Python with sync and asyncio clients.

MCP client configuration
{
  "mcpServers": {
    "nofeb": {
      "url": "https://API_HOST/mcp",
      "headers": { "Authorization": "Bearer YOUR_KEY" }
    }
  }
}

Or sign in with OAuth

Clients that cannot send a custom header, such as custom connectors in claude.ai and ChatGPT, connect by signing in. Give the client the MCP server URL and nothing else: a request without a credential is answered 401 with a pointer to the server's OAuth metadata, the client registers itself, and a person signs in to the nofeb console, picks the organization and optionally one inbox, and approves the scopes the client may use.

The flow is OAuth 2.1: dynamic client registration or a client ID metadata document, authorization code with PKCE, tokens bound to the MCP server they were issued for, and refresh tokens that rotate on every use, where a reused one revokes the whole grant. An OAuth token reaches exactly what an API key with the same scopes would. Connected apps are listed per organization and disconnected with one call, effective immediately. See the claude.ai and ChatGPT guides.

What a client discovers
POST https://API_HOST/mcp            (no credential)
401  WWW-Authenticate: Bearer resource_metadata="https://API_HOST/.well-known/oauth-protected-resource/mcp"

GET  /.well-known/oauth-protected-resource/mcp
GET  /.well-known/oauth-authorization-server
POST /oauth/register      dynamic client registration
GET  /oauth/authorize     PKCE S256; a person approves in the console
POST /oauth/token         access token and rotating refresh token
POST /oauth/revoke

GET    /v1/oauth/grants              connected apps
DELETE /v1/oauth/grants/{grant_id}   disconnect one

Tested against the clients people use

A conformance suite runs on every change to the engine: the official TypeScript and Python MCP SDK clients and the MCP inspector connect to a running server and go through initialization, listing tools, representative tool calls, error mapping, matching structured and text results, and the whole OAuth flow from registration and consent to refresh rotation, step-up and revocation.

Mail an agent can prove it sent

Register each agent with a name, a human sponsor and the API keys it acts through. Mail it sends carries an agent header and a signature over the sender, recipients, subject and body, which anyone can check against your organization's published keys, or by posting the raw message to nofeb's verification call with no key at all. Revoke an agent and its keys stop sending, and its earlier mail verifies as revoked.

Agents that sign in without an API key

An agent running in Azure, Google Cloud, Amazon EKS or GitHub Actions can skip the stored key: it exchanges the token its platform already gives it (Microsoft Entra ID or Entra Agent ID, a Google service account, an EKS service-account token, a GitHub Actions OIDC token, or any OIDC issuer) at nofeb's OAuth token endpoint for a short-lived access token, and uses it on the API, the MCP server, JMAP and the realtime stream. You decide which subject, and which repository or branch, acts as which registered agent, with which scopes and in which pod or inbox; a dry-run call explains why a pasted token would or would not be accepted. Its mail is signed as the agent and names the external identity that acted.

Status of everything on this page

Every capability named above, with its status as reconciled against the engine.

CapabilityWhat it doesStatus
Agent self-signup with a human sponsor An agent creates its organization, first inbox and API key in one unauthenticated call. Until the human sponsor it names verifies by email, it may only reply to people who wrote to it first. Shipped
Sponsor gating on unverified organizations Until a human sponsor verifies, an organization may only reply, and only to addresses that wrote to it in that thread. Shipped
Unlimited inboxes Create as many inboxes as the work needs, with a generated or chosen address and an idempotent client reference. Shipped
Disposable inboxes with a time to live Give an inbox a lifetime in seconds; it and its mail are removed when it expires, and an event says so. Shipped
Wait for an email Long-poll an inbox for up to a minute until a message matching sender, subject or has-a-code arrives. Shipped
One-time code and link extraction Verification codes and classified links are pulled out of every message and returned as fields. Shipped
LLM-ready thread context A whole thread, oldest first, with safe_body text and the thread's metadata, in one call. Shipped
MCP server A remote MCP server over streamable HTTP whose tools are generated from the same operation table as the REST API and dispatched through the same router, so a tool cannot behave differently from its endpoint. Shipped
MCP sign-in with OAuth MCP clients connect by signing in instead of pasting a key: OAuth 2.1 with discovery, dynamic client registration, client ID metadata documents, PKCE, tokens bound to the MCP server, refresh-token rotation and immediate revocation. A person approves the scopes, and optionally one inbox, in the console, and can disconnect the app at any time. API keys keep working beside it. Shipped
MCP client conformance suite The official TypeScript and Python MCP SDK clients and the MCP inspector drive the server in CI on every change: initialization, tool listing, tool calls, error mapping and the full OAuth sign-in flow. Shipped
OpenAPI document A published OpenAPI document kept identical to the served routes by a parity test. Shipped
TypeScript and Python SDKs Official clients generated from the OpenAPI document: @nofeb/sdk for Node, Deno, Bun and edge runtimes, and nofeb for Python with sync and asyncio clients. Both chain long polls for waitForEmail, retry idempotent requests, page through lists and verify webhook signatures. Shipped
Agent identity and signed mail Register each agent with a name, a human sponsor and the keys it acts through. Its mail carries an agent header and a signature over the sender, recipients, subject and body that anyone can check against your organization's published keys or nofeb's verification call. Revoking an agent stops its keys from sending and marks its mail as revoked. Shipped
Agent identity federation (no stored API key) An agent signs in with the identity its cloud or CI platform already gives it: Microsoft Entra ID or Entra Agent ID (v2.0 tokens), Google service accounts, Amazon EKS service-account tokens (IRSA), GitHub Actions OIDC tokens, or any OIDC issuer. Your organization trusts the issuer and binds an exact subject, plus optional claim conditions such as the repository and branch, to a registered agent with a scope ceiling and an optional pod or inbox restriction. The agent exchanges its token (OAuth 2.0 token exchange, RFC 8693) for a short-lived nofeb access token with no refresh token, usable on the API, MCP, JMAP and the realtime stream. No secret is stored: keys come from the issuer's published signing keys, and each external token is accepted once. Deleting the binding or issuer, or revoking the agent, ends its sessions at once; every exchange is audited, a dry run explains why a token would or would not be accepted, and mail the agent sends carries the external identity in its signed agent claims. Shipped