research(gateway): evaluate Open Connector as an MCP/OAuth integration layer

[toby-bridges]

Problem

Raven currently implements its messaging gateway through first-party channel adapters for Telegram, Slack, Discord, Matrix, WhatsApp, Feishu, WeCom, and other platforms. As the number of integrations grows, it is worth asking whether Raven should reuse an open connector layer instead of owning every integration concern directly.

Open Connector presents itself as an open-source, self-hostable connector platform and MCP gateway for AI agents. It centralizes OAuth, credential storage, tool discovery/execution, scoped access, and audit logging across third-party services.

However, its use of the word “gateway” describes a different boundary from Raven's current gateway:

• Raven's gateway primarily receives and delivers conversational messages and routes them into the Raven runtime.
• Open Connector primarily brokers agent-initiated tool calls to third-party APIs over MCP, SDK, or HTTP while managing credentials.

Before adopting it, we should determine whether it is a replacement for any Raven component, a complementary tool/credential layer, or simply useful prior art.

Proposal

Evaluate Open Connector as a possible integration layer for Raven, with the following questions:

1. Architectural fit

   • Could Raven consume Open Connector as an external MCP server or API service?
   • Would it complement the existing messaging gateway rather than replace channel intake/outlet adapters?
   • Which responsibilities should remain native to Raven: inbound events, conversation identity, delivery semantics, permissions, retries, and media handling?

2. Potential value

   • Managed OAuth and token refresh for per-user connections.
   • Server-side credential injection so raw third-party tokens do not enter agent context.
   • Connector/tool discovery through MCP or a typed API.
   • Scoped tool allowlists, key rotation, and tamper-evident audit records.
   • Reduced duplication when adding services such as GitHub, Notion, Linear, Google Drive, or Slack as agent tools.

3. Messaging-versus-tool semantics

   • Determine whether Open Connector supports the inbound event and bidirectional conversation semantics Raven gateways require, or only agent-initiated API actions.
   • Avoid treating a Slack or Discord tool connector as equivalent to a full Raven channel adapter without verifying events, threads, mentions, attachments, acknowledgements, retries, and identity mapping.

4. Operational and security cost

   • Self-hosting requirements, including its service runtime, Postgres, encryption-key custody, OAuth app setup, migrations, upgrades, and failure recovery.
   • Whether adding a network credential broker improves or complicates Raven's current local-first trust boundary.
   • Behavior when Open Connector is unavailable, and whether Raven can degrade cleanly.

5. Maturity and licensing

   • Open Connector is currently advertised as private beta.
   • As of 2026-07-23, its public GitHub repository contains only a README and AGPL-3.0 license; it says the source is still being prepared, and it has no published releases.
   • Raven is Apache-2.0, so the team should review the AGPL boundary before vendoring, linking, modifying, or distributing Open Connector. Running it as a separately deployed service may create a different boundary, but this should be confirmed rather than assumed.

Suggested evaluation path

1. Wait until the implementation source is publicly available and can be audited.
2. Review its connector contract, event/webhook support, authentication model, deployment footprint, tests, and release practices.
3. Build a small external-service spike using one non-channel integration, such as GitHub or Notion, through MCP/API.
4. Compare that spike with a native Raven integration on setup effort, credential exposure, permission granularity, latency, failure handling, and maintenance cost.
5. Record a decision: adopt as an optional external connector backend, borrow selected design ideas, or keep Raven integrations native.

The spike should not replace an existing Raven channel adapter until the messaging semantics and operational trade-offs are demonstrated.

Alternatives considered

• Continue implementing all messaging channels and third-party tools directly in Raven.
• Support generic MCP servers and let users connect Open Connector without a dedicated integration.
• Borrow its credential-broker and audit concepts while keeping Raven's implementation independent.
• Revisit the project after its source and stable releases become available.

Area

Channels / gateway

Additional context

• Product: https://openconnector.dev/
• MCP gateway overview: https://openconnector.dev/mcp-gateway
• Documentation: https://docs.openconnector.dev/docs/getting-started
• Public repository: https://github.com/openconnector-dev/openconnector

This issue requests an architectural evaluation only. It does not propose an immediate dependency or migration.