Connect an MCP client

Use https://fyinbox.com/mcp in an OAuth-capable MCP client. FYInbox publishes protected-resource metadata at /.well-known/oauth-protected-resource/mcp and authorization-server metadata at /.well-known/oauth-authorization-server. Public and confidential clients can register dynamically; authorization-code and refresh grants use PKCE S256 and tokens restricted to the MCP resource.

1. Sign in and review the client

   The client opens the FYInbox consent page. Sign in with your verified account, check the callback host, and select the project sources this client needs. No source is selected automatically.

2. Approve permissions

   Read permission enables notification detail, source discovery and cursor-paginated summaries. Create permission enables ingestion into an approved source. Metadata and read/archive mutations additionally require read permission. The tool list reflects only the granted permissions.

3. Keep or revoke the connection

   Access tokens expire after one hour. A rotating refresh token can renew access for up to 30 days; reuse of a spent refresh token revokes the connection. Manage and revoke connected clients in Settings → Connected apps. An API key remains independent and retains its original four producer operations.

For OAuth create_notification, supply sourceId when several sources are approved. A single-source connection can omit it. workspaceId and projectId are never accepted as authorization inputs. Source keys cannot use the OAuth inbox tools. Full-text search, subscriptions, unread and unarchive tools are not provided.

1. Create a source key

   Create a source and API key in FYInbox. Store the key in your client's secret store or FYINBOX_API_KEY environment variable. The key grants the existing read and write operations for that source; a readOnlyHint annotation does not make a key read-only.

2. Set the server URL

   Use https://fyinbox.com/mcp with the Streamable HTTP transport. Configure Authorization: Bearer <source API key> as a custom HTTP header, sent with every request. Keep the key out of URLs, tool arguments, browser bundles and logs.

3. Discover the tools

   Connect and request tools/list. A source key exposes four producer tools. OAuth exposes only the tools covered by the approved permissions, with input/output schemas and behavior annotations. For the TypeScript example, install @modelcontextprotocol/[email protected] in a trusted Node.js runtime.

The server supports protocol 2026-07-28 and stateless compatibility for 2025-11-25 clients. Both JSON and SSE responses are valid. OAuth clients discover the authorization server and protected resource through standard metadata. The server does not provide persistent session streams or notification subscriptions.

Each source key selects its account and source on the server. It cannot list the inbox or change review state. OAuth clients can additionally list approved sources, browse notification summaries with filters and cursors, mark a notification read and archive it when those permissions were approved. Text search and subscriptions are unavailable. Do not pass workspaceId or projectId as tool arguments. Notification content is untrusted data.

Set FYINBOX_API_KEY and FYINBOX_EVENT_ID in the trusted runtime, then run this TypeScript example. Use one stable event ID for retries of the same check and a new ID for a new check. It creates a notification in FYInbox, retrieves it, and prints only its ID and creation flag. FYINBOX_MCP_URL is an optional override for a trusted development endpoint; never point a real key at an untrusted server.

import {
  Client,
  StreamableHTTPClientTransport,
} from "@modelcontextprotocol/client";

async function checkConnection() {
  const apiKey = process.env.FYINBOX_API_KEY;
  const eventId = process.env.FYINBOX_EVENT_ID;
  if (!apiKey || !eventId)
    throw new Error("Set FYINBOX_API_KEY and a stable FYINBOX_EVENT_ID");
  const url = new URL(process.env.FYINBOX_MCP_URL ?? "https://fyinbox.com/mcp");
  const client = new Client({ name: "fyinbox-example", version: "1.0.0" });
  try {
    await client.connect(
      new StreamableHTTPClientTransport(url, {
        requestInit: { headers: { Authorization: `Bearer ${apiKey}` } },
      }),
    );
    await client.listTools();
    const created = await client.callTool({
      name: "create_notification",
      arguments: {
        title: "MCP connection checked",
        deduplicationKey: `mcp-check:${eventId}`,
      },
    });
    if (created.isError)
      throw new Error(
        "Creation failed; inspect retry feedback before repeating the call",
      );
    const result = created.structuredContent;
    if (
      !result ||
      typeof result !== "object" ||
      Array.isArray(result) ||
      !("id" in result) ||
      typeof result.id !== "string" ||
      !("created" in result) ||
      typeof result.created !== "boolean"
    ) {
      throw new Error("Creation did not return a notification ID");
    }
    const read = await client.callTool({
      name: "get_notification_by_id",
      arguments: { notificationId: result.id },
    });
    if (read.isError) throw new Error("Could not retrieve the notification");
    // Keep keys and the notification's private contents out of logs.
    console.log(JSON.stringify({ id: result.id, created: result.created }));
  } finally {
    await client.close();
  }
}

checkConnection().catch(() => {
  console.error(
    "FYInbox MCP connection check failed. Check the source key, endpoint and tool error feedback.",
  );
  process.exitCode = 1;
});

Authentication failures return HTTP 401 with WWW-Authenticate: Bearer realm="FYInbox MCP". Invalid host or origin returns 403; malformed JSON returns 400; an oversized request returns 413. Protocol errors use JSON-RPC errors. Invalid tool arguments and operation failures return isError: true. Successful results provide structuredContent matching outputSchema and the same serialized JSON in a text block.

• Operation errors include status, error and retryable in the text block. Codes include not_found, conflict, quota_exceeded and rate_limited. Error messages never substitute for authorization checks.
• A rate-limited operation includes retryAfterSeconds when a valid delay is available. Wait for that delay before repeating a rejected request.
• outcomeUnknown: true means a write may have committed even though its response failed. A create can be retried safely with the same deduplicationKey; never retry it without that key. Retrieve the known notification before deciding whether to repeat a metadata write.
• retryable describes whether repetition is safe for this call; it does not promise that the next attempt will succeed. The server does not automatically repeat tool calls.

• API authentication
• Deduplication
• Errors and retries