[EPIC] Vercel Eve Integration — Registry + OAuth

[replynodes-ai]

Parent distribution Epic: #8

Objective

Make ReplyNodes a first-class Vercel Eve integration that can be discovered and installed with:

eve add connection/replynodes

and ultimately use Vercel Connect-managed OAuth so Eve users can authorize ReplyNodes without manually copying API keys.

This Epic intentionally delivers both phases:

1. Phase 1 — Official Eve registry integration using API-key auth
2. Phase 2 — First-class Vercel Connect OAuth integration

The work is not complete until both phases are implemented, verified, and upstreamed where required.

---

Canonical ReplyNodes inputs

• Production MCP: https://mcp.replynodes.com/mcp
• GitHub repo: https://github.com/replynodes/replynodes-mcp
• Official MCP Registry namespace: com.replynodes/mcp
• Auth today: ReplyNodes API key / bearer token
• Target Eve install command: eve add connection/replynodes

Product positioning

Use capability-oriented metadata rather than brand-only metadata.

Recommended description:

ReplyNodes provides web search, web scraping, website crawling, Reddit, YouTube, App Store, brand intelligence, and other public web/data tools for AI agents through one read-only MCP endpoint.

Do not claim capabilities that are not live in production.

---

Phase 0 — Upstream alignment first

Eve's contribution guide requires opening an issue and getting maintainer alignment before investing in a non-trivial registry integration.

Required work

1. Research the latest vercel/eve contribution guide and current connection registry patterns.
2. Study current official Eve MCP connection implementations and comparable open/pending integrations to follow the native architecture and contribution expectations.
3. Open an upstream issue in vercel/eve proposing connection/replynodes before implementation if no equivalent issue already exists.
4. In the issue, clearly explain:
   • production MCP endpoint
   • ReplyNodes capabilities
   • why Eve agents benefit from the integration
   • Phase 1 API-key auth path
   • Phase 2 Vercel Connect OAuth path
   • preferred final UX: eve add connection/replynodes
5. Wait for or respond to maintainer direction before sending broad upstream implementation changes.

Important Eve contribution requirements

Any upstream PR must follow Eve contribution rules, including:

• verified signed commits
• DCO Signed-off-by on every commit
• PR linked to an upstream issue
• Node/pnpm versions required by Eve
• relevant lint/typecheck/test/registry checks

---

Phase 1 — Official Eve Registry integration with API-key auth

Goal

Ship ReplyNodes into Eve's official registry as a discoverable MCP connection without waiting for OAuth catalog work.

Expected user experience:

eve add connection/replynodes

The generated connection should mount under something equivalent to:

agent/connections/replynodes.ts

Implementation direction

Use defineMcpClientConnection from eve/connections and authenticate against the production MCP using REPLYNODES_API_KEY.

Follow the current Eve-supported auth/header pattern; do not assume the exact implementation shape before reading the current source.

Conceptually:

export default defineMcpClientConnection({
  url: "https://mcp.replynodes.com/mcp",
  description: "ReplyNodes: web search, scraping, crawling, Reddit, YouTube, App Store, brand intelligence, and public web data for AI agents.",
  // auth/header resolver using REPLYNODES_API_KEY
});

Expected upstream registry changes

Research current Eve layout first, but expect work in areas such as:

• apps/docs/registry/connections/replynodes.ts
• apps/docs/registry.json
• Eve catalog identity
• gallery/integration metadata
• ReplyNodes logo
• setup guidance
• validation/tests for API-key-backed MCP connections

Avoid broad framework changes unless maintainers explicitly request them.

Environment/config

Use a clearly named env var:

REPLYNODES_API_KEY

The setup flow must explain where users obtain a key and must never expose the key to the model or conversation context.

Phase 1 validation

Must verify all of the following:

• pnpm --filter eve-docs registry:check passes
• relevant Eve lint/typecheck/tests pass
• docs/integration page renders correctly
• eve add connection/replynodes works in a clean fixture/project
• generated file lands at the expected target path
• ReplyNodes MCP initializes successfully
• tools/list succeeds
• at least one authenticated production ReplyNodes tool call succeeds
• the model can discover ReplyNodes through Eve's connection_search

Test non-brand discovery intents such as:

• web search
• web scraping
• reddit
• youtube
• app store
• brand intelligence

Phase 1 Definition of Done

• Upstream Eve issue exists and direction is agreed
• connection/replynodes exists in the official Eve registry
• eve add connection/replynodes works
• API-key setup uses REPLYNODES_API_KEY
• registry validation passes
• clean install passes
• real production MCP smoke test passes
• public Eve integration/gallery page is live if supported
• upstream PR is merged

---

Phase 2 — Vercel Connect OAuth integration

Goal

Upgrade ReplyNodes from manual API-key setup to a first-class Vercel Connect OAuth experience using the current official Eve/Vercel Connect pattern.

Target UX:

1. User installs connection/replynodes.
2. Eve requests authorization when ReplyNodes is first needed.
3. Browser opens the ReplyNodes authorization flow.
4. User authorizes access.
5. Vercel Connect stores/retrieves the user-scoped token.
6. Eve calls ReplyNodes MCP without the API key being copied into the project.

Technical direction

Use the current official Eve/Vercel Connect integration pattern:

import { connect } from "@vercel/connect/eve";
import { defineMcpClientConnection } from "eve/connections";

export default defineMcpClientConnection({
  url: "https://mcp.replynodes.com/mcp",
  description: "...",
  auth: connect("<replynodes-connector-id>"),
});

The exact connector identifier must come from the real Vercel Connect configuration. Do not invent one.

ReplyNodes OAuth readiness

The agent must verify whether the production ReplyNodes MCP/auth stack already satisfies the OAuth/OIDC requirements needed by Vercel Connect.

If not, implement the minimum standards-compliant OAuth flow required for this integration, including where applicable:

• authorization endpoint
• token endpoint
• client registration/discovery expectations
• redirect URI handling
• PKCE where required
• refresh/access-token lifecycle
• user-scoped authorization
• secure token handling
• revocation/logout behavior where applicable
• MCP authorization compatibility

Do not weaken authentication or expose long-lived secrets to clients just to make the integration work.

Vercel Connect work

Research the latest Vercel Connect provider/connector process and determine whether ReplyNodes needs:

• a connector created by ReplyNodes
• service catalog inclusion
• Vercel-side review/approval
• domain/OAuth discovery configuration
• additional metadata or security review

If Vercel approval or owner-only setup is required, ask the owner for exactly the specific action needed.

Migration behavior

Once OAuth is available:

• preserve API-key auth as a documented fallback if technically useful
• prefer OAuth for the official Eve registry integration
• do not break existing API-key users unnecessarily
• document migration clearly

Phase 2 validation

Must test a true end-to-end user flow:

1. clean Eve project
2. eve add connection/replynodes
3. no REPLYNODES_API_KEY configured
4. model attempts to use ReplyNodes
5. Eve emits authorization-required state
6. browser authorization completes
7. Vercel Connect returns/stores a user-scoped credential
8. MCP reconnects successfully
9. tools/list succeeds
10. real ReplyNodes tool call succeeds
11. subsequent calls do not require reauthorization until appropriate
12. expired/revoked authorization fails safely and can reauthorize

Phase 2 Definition of Done

• ReplyNodes OAuth flow is production-ready for Vercel Connect
• Vercel Connect connector/provider configuration exists
• Eve connection uses @vercel/connect/eve
• OAuth is user-scoped where appropriate
• no API key is required for the primary Eve flow
• clean authorization flow passes end-to-end
• refresh/re-auth behavior is verified
• real production MCP call succeeds after OAuth
• upstream Eve registry integration is updated to OAuth
• public docs show the final OAuth-based install/use flow

---

Discovery and quality requirements

The integration must be optimized for agent discovery inside Eve, not only for the ReplyNodes brand.

The description/setup metadata should make it clear that ReplyNodes covers:

• web search
• web scraping
• website crawl/map
• Reddit/public social data
• YouTube data
• App Store data
• brand intelligence
• public web/data context for agents

Where Eve supports integration search/gallery metadata, test discovery using these capability terms.

---

Security requirements

• Never place API keys or OAuth tokens in prompts, model-visible context, logs, committed files, or screenshots.
• Use Eve/Vercel Connect credential handling as designed.
• Keep ReplyNodes read-only positioning accurate.
• Verify least-privilege/scoped OAuth behavior where supported.
• Document any tool that has non-obvious cost/credit implications.
• Do not add unrelated Eve framework changes just to make the integration mergeable.

---

Agent autonomy

Hermes should perform all research, code changes, testing, upstream issue/PR preparation, maintainer follow-up, and verification it can perform.

Only ask the owner for actions that truly require owner privileges, for example:

• Vercel account/organization authorization
• creation/approval of a Vercel Connect connector that cannot be delegated
• OAuth client secrets or protected production configuration
• DNS/domain verification
• legal/provider acceptance
• GitHub organization permissions unavailable to the agent

When blocked, ask for exactly one concrete action with the exact URL/field/value required, then continue after it is completed.

---

Epic Definition of Done

This Epic is complete only when both phases are done:

1. ReplyNodes is merged into the official Eve registry and installable via eve add connection/replynodes.
2. A real API-key-backed production connection has been proven end-to-end.
3. ReplyNodes is integrated with Vercel Connect OAuth.
4. The official Eve integration has been upgraded to the OAuth flow.
5. A clean user can install, authorize, discover, and call ReplyNodes without manually copying an API key.
6. Capability-based discovery has been tested.
7. Final upstream issue/PR URLs, integration page, install command, and verification evidence are recorded here.

Do not mark this Epic complete after Phase 1 only. The final goal is a first-class Eve integration with a seamless OAuth authorization flow.

[replynodes-ai]

jack-dev implementation gate result (2026-09-15): BLOCKED safely. Verified repo https://github.com/replynodes/replynodes-fetcher.git, origin/main, MCP transport, API-key auth, billing schema, config, and deployment. Fetcher is explicitly read-only/stateless and has no OAuth clients, authorization grants/codes, access/refresh tokens, revocation model, issuer/signing key, client registry, or callback config; identity/users/workspaces remain in the separate control plane. Live metadata probes: /.well-known/oauth-protected-resource = 404 and /.well-known/oauth-authorization-server = 404. No files changed, no commit/PR created. Baseline checks passed: go test ./internal/mcp ./internal/gateway, go build ./..., go vet ./..., gofmt, git diff --check. Secret scan has a pre-existing committed third_party certifi PEM finding and is not a new regression. Next prerequisite: design/implement the OAuth authorization-server boundary in the actual control-plane owner, then wire Fetcher resource-server validation; do not create an Eve PR or invent a Connect connector before that.