Connect a client
Add the Letterby MCP server to Claude, Cursor, Codex, VS Code or your own client.
Add this URL to any MCP client that supports remote servers with OAuth:
https://api.letterby.com/mcpAdd the server
Open Settings, then Connectors, then Add custom connector. Paste the URL and select Connect.
Approve access
The first time you connect, your browser opens Letterby.
Sign in to your Letterby account if you are not signed in.
Check the app. The screen names the client and lists what it will be able to read. Apps Letterby has not reviewed are marked Unverified app.
Pick the workspace. If you belong to more than one team, choose which one the client may read. Access covers that team only.
Confirm it's you, if asked. Enter a code from your authenticator app, or a 6-digit code sent to your email.
Select Allow access. You return to your client, connected.
Only approve a client you just started yourself. If a consent screen appears that you did not expect, select Deny.
Disconnect
Open your account settings in Letterby, select the MCP tab, find the app and select Revoke. Access ends on the client's next request.
Troubleshooting
| Problem | Fix |
|---|---|
| The browser never opens | Your client must support remote MCP servers with OAuth. Update it, then add the server again. |
| "No teams found" | Your account is not a member of an active team. Create or join one, then reconnect. |
| Sent to a two-factor setup page | Your team requires two-factor authentication. Turn it on, then reconnect. |
| Tools stop working after a while | Access was revoked, or you left the team. Connect again. |
rate_limited | A connection can make 30 tool calls per minute. Wait a minute. |
Build your own client
The server follows the MCP authorization spec. A client needs no prior setup with Letterby.
| Topic | Value |
|---|---|
| Transport | Streamable HTTP. JSON-RPC 2.0 over POST, stateless, no SSE. |
| Protocol version | 2025-06-18 |
| Discovery | GET https://api.letterby.com/.well-known/oauth-protected-resource names the authorization server. |
| Client registration | Client ID Metadata Document (an https URL as client_id) or Dynamic Client Registration. Public clients only, no client secret. |
| Authorization | Authorization code with PKCE S256. state is required. |
resource parameter | Required on authorize and token requests: https://api.letterby.com/mcp |
| Redirect URIs | https, or http on localhost, 127.0.0.1 or [::1] with any port. Custom URI schemes are not accepted. |
| Access token | Valid for 10 minutes. Send it as Authorization: Bearer <token>. |
| Refresh token | Valid for 30 days. Each use returns a new pair; the old refresh token stops working. |
A request without a valid token returns 401 with a WWW-Authenticate header that points to the discovery document.