MCP server
Connect an AI client to your GoodInboxes workspace using scoped Streamable HTTP.
The MCP endpoint is https://www.goodinboxes.com/api/mcp. The transport is stateless Streamable HTTP with JSON POST responses. Authenticated GET and DELETE return 405; there is no SSE subscription or persistent session.
Connect ChatGPT
Add https://www.goodinboxes.com/api/mcp as a custom MCP connector in ChatGPT. GoodInboxes will show a sign-in and consent screen. Sign in as a workspace owner or admin and approve the scopes shown there. Reads are the default; explicitly requested write scopes are available only when the operator enables writes. Existing connections must reconnect to request write access. The connection creates a revocable GoodInboxes token with the explicitly approved scopes that expires after 30 days. Reconnect when it expires.
Other MCP clients
Clients that support custom headers can create a token in MCP access with the mcp scope and each resource scope they need. Send Authorization: Bearer TOKEN and keep the token in a trusted process.
Connect with the TypeScript SDK
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
const client = new Client({ name: "my-integration", version: "1.0.0" });
await client.connect(
new StreamableHTTPClientTransport(new URL("https://www.goodinboxes.com/api/mcp"), {
requestInit: { headers: { Authorization: "Bearer " + process.env.GOODINBOXES_API_TOKEN } },
}),
);
try {
const result = await client.callTool({ name: "get_context", arguments: {} });
if (result.isError) throw new Error("mcp_read_failed");
} finally {
await client.close();
}Available tools
| Area | Tools | Required resource scopes |
|---|---|---|
| Workspace | get_context | context:read |
| Inboxes | list_inboxes, get_inbox | inboxes:read |
| Domains | list_domains, get_domain, check_domain_availability, check_google_domain_eligibility | domains:read |
| Orders | list_orders, get_order, get_order_fulfillment, inspect_inventory_purchase | orders:read |
| Wallet | get_wallet_balance | wallet:read |
| Sequencer | list_sequencer_tags | sequencer:read |
| Sequencer writes | assign_sequencer_tag, reconcile_sequencer_tag | sequencer:tags:write plus separate write flag |
Every tool also requires mcp. Available tools are filtered by the token's scopes. Read the goodinboxes://operations-guide resource first. Tool failures return isError: true and a safe error code. A payment or provisioning status of unknown or pending must never trigger a second payment or provider action.
Limits
MCP exposes no wallet top-up, cancellation, credentials, internal provider logs, warmup write, or staff control tools. Purchases require the explicitly enabled order tools described below. Tag assignment additionally requires explicit consent, a stable request ID, and owned inbox IDs. Reconcile an uncertain tag result with the same request ID instead of starting a blind new assignment.
Domain forwarding
set_domain_forwarding({id,targetUrl,consent:true}) requires domains:forwarding:write, mcp and the separate write flag. Approve the exact owned domain and destination before sending consent. verified confirms an independently read Cloudflare redirect rule; public DNS and HTTP delivery remain unverified. Concurrent changes can supersede one another. An uncertain response may follow an applied change; inspect the result before retrying.
Order tools
Explicitly enabled orders:write access adds quote_order and place_order; get_order_quote reads the original command without repeating payment. list_order_options needs orders:read and discovers inventory bundles or eligible owned domains.
Pass the complete cart as quote_order({ order: cart }). Ask the customer to approve the quoted selections, upfront amount, monthly renewal cost, checkout/financial policy versions, and any BYOD takeover before calling place_order. Use the exact quote values and keep the same confirmation on retry. Pending or unknown payment is not permission to create a new order. Native provider fulfillment remains separately observable.