Skip to content

Self-improving AI Employees for everyone

feat(connectors): an MCP server card on the Connectors page

trohitgeec2c29ef483
diff --git a/CLAUDE.md b/CLAUDE.md
index 1fd2aba8..6716103b 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -33,7 +33,7 @@ This is a React Flow-based workflow automation platform implementing n8n-inspire
| **[Email Service](./docs-internal/email_service.md)** | IMAP/SMTP integration via Himalaya CLI with EmailService orchestrator, provider presets, custom credential fallback, and polling triggers |
| **[Browser](./docs-internal/browser.md)** | Current `browser` node: installed Chrome/Edge/Chromium in a dedicated profile rendered inside the workspace by default (`BROWSER_RUNTIME=system`, `BROWSER_HEADLESS=true`) and pinned browser-use CLI. Chrome for Testing requires explicit `BROWSER_RUNTIME=testing`. System mode retains the native user agent and OS password-store/keychain integration; basic/mock keychain flags are restricted to testing mode. Includes persistent employee/shared profiles (the Credentials / Connectors "Web browser" panel adds, deletes and imports logins from a session file; the node's profile dropdown lists only the caller's profiles, via `current_load_options_principal()`), session leases, agent/user handoff, network policy, screenshots as workspace FileRefs and authenticated `/ws/browser` live viewing. Plugin-owned installation is lazy (`_install_chrome.py`, `_install_bu.py`); importing or shutting down the plugin never installs it. Replaces the former agent-browser and separate `browserHarness` implementations. |
| **[Browser Workspace](./docs-internal/browser_workspace.md)** | Home and Dev share `WorkspaceTabs` and `BrowserWorkspace`: Browser / Canvas / Mobile, capability-based discovery, binary JPEG frames, bounded frame credit and decoding, Take control / Hand back, the agent's cursor (`agent_action`: where each click, hover, type or select happened, beside the agent's result and never during a protected login), visibility cleanup and payload-free opt-in diagnostics. The Browser node's parameter panel shows the same viewer, and the Dev dock opens on its Browser tab when an agent in the open workflow asks for help (`browser_updated`). Mobile shows the managed local Android phone. |
-| **[MCP Connectors](./docs-internal/mcp_connectors.md)** | Custom connectors: the owner adds an outside MCP server from Connectors → Add (URL, name, sign-in: none, bearer, one header, or OAuth), and OpenCompany is its MCP *client* (`server/nodes/mcp/`, official `mcp` SDK; unrelated to the CLI agents' `/mcp/ide` server). The server reads the tools before keeping anything: streamable HTTP, then SSE; our own httpx client with redirects off; host and resolved addresses of every request (an OAuth sign-in's to its authorization server too) checked against `services/netpolicy.py` (shared with the Browser node: never cloud metadata or OpenCompany's own ports, plain http only on the owner's network), within `DISCOVER_S` (45 s, under the app's 60 s probe wait). Kept as `mcp:<slug>` (sign-in, encrypted; plain `model_params._mcp`: tools as accepted, per-tool `{enabled, ask}`, a waiting refresh) and `mcp:<slug>_proxy` (URL). A tool no model could call is kept with the reason, never renamed. Each connector is its own card through the generic `Credential.catalogue_entries` hook and the `_mcp_connector` template. Commands `mcp_connector_add` / `_sign_in` / `_test` / `_refresh` / `_review` / `_set_tool` / `_remove`; Refresh holds every change for Accept. Client: `AddConnectorForm.tsx` and `panels/McpConnectorPanel.tsx`. The `mcpConnector` node on an agent's Tools gives one tool per tool that is on (`ToolNode.tool_bindings`, named `<slug>__<tool>`, run with its binding's locked `mcp_tool` / `mcp_ask` / labels; arguments checked with jsonschema, a `$ref` followed only inside its schema: a tool whose inputs refer to another document is unusable, and a call goes as a plain `tools/call`, so the SDK never checks a result against an output schema the server sends; Ask first per tool through the node's `approval` spec); CLI agents leave it out and RLM refuses it. OAuth (`_oauth.py`) is the SDK's `OAuthClientProvider`: Add or Sign in again answers `sign_in_url`, the sign-in finishes in the background through `/api/mcp/oauth/callback`, tokens go to the OAuth token store under `mcp:<slug>` with their expiry (`store_oauth_tokens(..., expiry=)`), and each connection restores the expiry (read uncached with `get_stored_oauth_tokens`) and the endpoints before first use, so the SDK refreshes instead of opening a sign-in; a token issued without an expiry is renewed once the server refuses it (`_oauth.connect`); a refused refresh says Sign in again. Each connector is also an app a hire can use: `connector_apps`, registered with `services/employees/apps.register_app_source`, is read by `Connections.apps` with `employee_apps.json`'s apps (a saved one counts as connected), `mcpConnector` is on the hire allowlist, and the employee's card reads the connector from the node's `app_field` (`mcp_connector`). |
+| **[MCP Connectors](./docs-internal/mcp_connectors.md)** | Custom connectors: the owner adds an outside MCP server from Connectors → Add, or the MCP server card in the Custom category (`mcp`, kind `mcpAdd`, never connected; its page `panels/McpAddPanel.tsx` is the same form) (URL, name, sign-in: none, bearer, one header, or OAuth), and OpenCompany is its MCP *client* (`server/nodes/mcp/`, official `mcp` SDK; unrelated to the CLI agents' `/mcp/ide` server). The server reads the tools before keeping anything: streamable HTTP, then SSE; our own httpx client with redirects off; host and resolved addresses of every request (an OAuth sign-in's to its authorization server too) checked against `services/netpolicy.py` (shared with the Browser node: never cloud metadata or OpenCompany's own ports, plain http only on the owner's network), within `DISCOVER_S` (45 s, under the app's 60 s probe wait). Kept as `mcp:<slug>` (sign-in, encrypted; plain `model_params._mcp`: tools as accepted, per-tool `{enabled, ask}`, a waiting refresh) and `mcp:<slug>_proxy` (URL). A tool no model could call is kept with the reason, never renamed. Each connector is its own card through the generic `Credential.catalogue_entries` hook and the `_mcp_connector` template. Commands `mcp_connector_add` / `_sign_in` / `_test` / `_refresh` / `_review` / `_set_tool` / `_remove`; Refresh holds every change for Accept. Client: `AddConnectorForm.tsx` and `panels/McpConnectorPanel.tsx`. The `mcpConnector` node on an agent's Tools gives one tool per tool that is on (`ToolNode.tool_bindings`, named `<slug>__<tool>`, run with its binding's locked `mcp_tool` / `mcp_ask` / labels; arguments checked with jsonschema, a `$ref` followed only inside its schema: a tool whose inputs refer to another document is unusable, and a call goes as a plain `tools/call`, so the SDK never checks a result against an output schema the server sends; Ask first per tool through the node's `approval` spec); CLI agents leave it out and RLM refuses it. OAuth (`_oauth.py`) is the SDK's `OAuthClientProvider`: Add or Sign in again answers `sign_in_url`, the sign-in finishes in the background through `/api/mcp/oauth/callback`, tokens go to the OAuth token store under `mcp:<slug>` with their expiry (`store_oauth_tokens(..., expiry=)`), and each connection restores the expiry (read uncached with `get_stored_oauth_tokens`) and the endpoints before first use, so the SDK refreshes instead of opening a sign-in; a token issued without an expiry is renewed once the server refuses it (`_oauth.connect`); a refused refresh says Sign in again. Each connector is also an app a hire can use: `connector_apps`, registered with `services/employees/apps.register_app_source`, is read by `Connections.apps` with `employee_apps.json`'s apps (a saved one counts as connected), `mcpConnector` is on the hire allowlist, and the employee's card reads the connector from the node's `app_field` (`mcp_connector`). |
| **[WhatsApp Business Service](./docs-internal/whatsapp_business_service.md)** | Official Meta Cloud API plugin in [`server/nodes/whatsapp_business/`](./server/nodes/whatsapp_business/) — **distinct from `nodes/whatsapp/`**, which is a personal account over an unofficial Go bridge; they share no node type, credential or palette group. Four nodes: `whatsappBusinessSend` (10 ops — Meta models message type as a *field* on one `/messages` endpoint, so text / media / template / interactive are operations, not nodes), `whatsappBusinessMedia` (the one genuinely separate endpoint family), and the `Receive` / `Status` triggers (kept separate because a canary trigger registers exactly one CloudEvents type). `phone_number_id` is deliberately **absent from Params** and comes from the credential only, because it selects the sending identity — `server_controlled_fields` would keep a model-set value out on every tool path, but an ActionNode's tool schema is its whole `Params` (`ToolInput` is ToolNode-only), so a declared field would still appear in the schema the model sees. Webhook via `register_webhook_source` on the shared catch-all, `X-Hub-Signature-256` HMAC failing closed, composite `wamid:status` dedup ids so `sent→delivered→read` don't collapse. |
| **[Stripe Service](./docs-internal/stripe_service.md)** | Stripe CLI integration — `stripeAction` (CLI pass-through) + `stripeReceive` (signed-webhook trigger, on a canvas Run and deployed: every Stripe event travels under one CloudEvents type, `com.opencompany.stripe.event.received`, with the Stripe type in `subject` and `data.event_type`, where the node's own `build_filter` reads it; the source shapes the payload once, wakes the in-process waiter through `WebhookSource.handle` and reaches deployed listeners through `dispatch.emit`; deploying starts `stripe listen` through the generic `TriggerNode.prepare_deployment` hook, at Start and at the boot re-arm). Reference plugin for the Wave 12 event framework AND the **CLI-managed-auth pattern**: browser OAuth via `stripe login --non-interactive` + `--complete <url>` (URL extracted from `next_step` shell command via `shlex.split`) + auto-installed binary (`ensure_stripe_cli` from GitHub releases) + marker-token reuse of `auth_service.store_oauth_tokens` + CloudEvents-shaped `broadcast_credential_event("credential.oauth.connected" \| ".disconnected", provider=...)` — zero per-provider hardcoding in the frontend. Daemon stdout/stderr ingested via `ProcessService`'s `line_handler` callback (no log-file tailing); credential gate routed through `await self.has_credential()` so non-api-key auth (`is_logged_in()`) plugs in via subclass override. |
| **[Vercel Service](./docs-internal/vercel_service.md)** | Vercel CLI integration — `vercelAction` (deploy / inspect / list + `custom` CLI passthrough; AI tool `vercel`). Second reference for the CLI-managed-auth pattern: the **device-flow variant** (`vercel login` is one blocking process — no two-step `--complete`; direct `create_subprocess_exec` + chunk-based banner read for the code-embedding URL, pumps drain pipes for the process lifetime, success gate = auth.json mtime advance + sniff). Dual auth: optional `vercel_token` field (injected as `VERCEL_TOKEN` env, never argv) OR CLI login with marker tokens. All invocations pin `--global-config <DATA_DIR>/vercel/` (the `CLAUDE_CONFIG_DIR` isolation idiom). `bun add` into the shared packages tree (pinned version, via `core/js_runtime.add_package`; the CLI runs on bun). First-deploy project guard raises `NodeUserError` instead of letting Vercel derive an invalid name from the workspace dir. Shipped with the generic OAuthConnect change: Login gates on **required** fields only, so optional fields never block CLI login. |
diff --git a/client/src/assets/icons/index.ts b/client/src/assets/icons/index.ts
index 0d6d5d87..3d4c5c16 100644
--- a/client/src/assets/icons/index.ts
+++ b/client/src/assets/icons/index.ts
@@ -59,6 +59,7 @@ import GoogleCloud from '@lobehub/icons/es/GoogleCloud';
import XAI from '@lobehub/icons/es/XAI';
import ElevenLabs from '@lobehub/icons/es/ElevenLabs';
import DeepL from '@lobehub/icons/es/DeepL';
+import MCP from '@lobehub/icons/es/MCP';
type RawSvg = string;
@@ -171,6 +172,7 @@ const LOBEHUB_BRANDS: Readonly<Record<string, any>> = {
xai: XAI,
elevenlabs: ElevenLabs,
deepl: DeepL,
+ mcp: MCP,
};
// The app's own mark (components/brand/geometry.ts) as `opencompany:mark`:
diff --git a/client/src/components/credentials/AddConnectorForm.tsx b/client/src/components/credentials/AddConnectorForm.tsx
index ce3c5cd8..5a4573a7 100644
--- a/client/src/components/credentials/AddConnectorForm.tsx
+++ b/client/src/components/credentials/AddConnectorForm.tsx
@@ -23,8 +23,11 @@ const FIELD = 'h-9.5 rounded-lg bg-bg-app text-row font-normal md:text-row dark:
const FAILED = "Couldn't add that connector. Try again.";
export interface AddConnectorFormProps {
+ /** Cancel, or an OAuth sign-in that goes on in its own tab. */
close: () => void;
- /** The connector was saved; `ref` is its card's id (`mcp:<slug>`). */
+ /** The connector was saved; `ref` is its card's id (`mcp:<slug>`). The
+ * host moves on from the form (the list closes it, the MCP server card's
+ * page opens the connector's). */
onAdded: (ref: string) => void;
}
@@ -61,8 +64,8 @@ export function AddConnectorForm({ close, onAdded }: AddConnectorFormProps) {
CREDENTIAL_PROBE_REQUEST_TIMEOUT,
);
if (result.success === false || !result.ref) throw new Error(result.error || FAILED);
- close();
if (result.sign_in_url) {
+ close();
window.open(result.sign_in_url, '_blank', 'noopener,noreferrer');
toast.info('Sign in on the page that opened. The connector shows here once you have.');
return;
diff --git a/client/src/components/credentials/CredentialsBrowser.tsx b/client/src/components/credentials/CredentialsBrowser.tsx
index 9f240508..d5600fa9 100644
--- a/client/src/components/credentials/CredentialsBrowser.tsx
+++ b/client/src/components/credentials/CredentialsBrowser.tsx
@@ -7,8 +7,9 @@
* custom (MCP) providers, after a confirmation; for the rest (a paired
* phone, an email account) it opens the panel, which owns those steps. A
* card glows when it turns connected. Connection-success feedback belongs
- * to the host. Add opens the custom connector form (AddConnectorForm); a
- * saved connector opens on its own page once the catalogue holds it.
+ * to the host. Add opens the custom connector form (AddConnectorForm), as
+ * does the MCP server card's page (panels/McpAddPanel); a saved connector
+ * opens on its own page once the catalogue holds it.
*/
import { useMemo, useState } from 'react';
@@ -192,7 +193,18 @@ function CredentialsBrowserContent({
onItemAdded={onItemAdded && ((item) => onItemAdded(item.id))}
primaryAction={
customConnectors
- ? { label: 'Add', form: (close) => <AddConnectorForm close={close} onAdded={(ref) => void openAdded(ref)} /> }
+ ? {
+ label: 'Add',
+ form: (close) => (
+ <AddConnectorForm
+ close={close}
+ onAdded={(ref) => {
+ close();
+ void openAdded(ref);
+ }}
+ />
+ ),
+ }
: undefined
}
/>
diff --git a/client/src/components/credentials/CredentialsModal.tsx b/client/src/components/credentials/CredentialsModal.tsx
index 55bda74d..8eeade68 100644
--- a/client/src/components/credentials/CredentialsModal.tsx
+++ b/client/src/components/credentials/CredentialsModal.tsx
@@ -103,6 +103,7 @@ function CredentialsSession({ visible, onClose, options }: Props & { options: Cr
backLabel={options.categoryId === 'ai' ? 'All AI models' : 'All connectors'}
onBack={allProviders}
visible={visible}
+ onOpen={(id) => setSelection({ id, intent: 'manage' })}
/>
)}
</Modal>
diff --git a/client/src/components/credentials/PanelRenderer.tsx b/client/src/components/credentials/PanelRenderer.tsx
index e70c1ca4..302c5037 100644
--- a/client/src/components/credentials/PanelRenderer.tsx
+++ b/client/src/components/credentials/PanelRenderer.tsx
@@ -25,6 +25,7 @@ const PANEL_LOADERS: Record<PanelKind, () => Promise<{ default: React.ComponentT
email: () => import('./panels/EmailPanel'),
browserProfiles: () => import('./panels/BrowserProfilesPanel'),
mcp: () => import('./panels/McpConnectorPanel'),
+ mcpAdd: () => import('./panels/McpAddPanel'),
};
// Memoize the lazy wrappers at module scope so switching providers of
@@ -38,6 +39,7 @@ const LAZY_PANELS: Record<PanelKind, React.LazyExoticComponent<React.ComponentTy
email: React.lazy(PANEL_LOADERS.email),
browserProfiles: React.lazy(PANEL_LOADERS.browserProfiles),
mcp: React.lazy(PANEL_LOADERS.mcp),
+ mcpAdd: React.lazy(PANEL_LOADERS.mcpAdd),
};
export interface CredentialPanelProps {
@@ -47,6 +49,8 @@ export interface CredentialPanelProps {
showTechnicalSections?: boolean;
/** Leave this provider's page: the panel removed the provider itself. */
onLeave?: () => void;
+ /** Show another provider's page: one the panel just added. */
+ onOpen?: (providerId: string) => void;
}
interface Props extends Omit<CredentialPanelProps, 'config'> {
@@ -66,7 +70,7 @@ const EmptyState: React.FC<{ icon: React.ReactNode; message: string }> = ({ icon
</div>
);
-const PanelRenderer: React.FC<Props> = ({ config, visible, showTechnicalSections = false, onLeave }) => {
+const PanelRenderer: React.FC<Props> = ({ config, visible, showTechnicalSections = false, onLeave, onOpen }) => {
const Lazy = useMemo(() => {
if (!config) return null;
return LAZY_PANELS[config.kind] ?? null;
@@ -97,7 +101,7 @@ const PanelRenderer: React.FC<Props> = ({ config, visible, showTechnicalSections
<Suspense fallback={<PanelFallback />}>
{/* Provider identity resets transient errors/reveal state. Mode changes
keep the same panel mounted and preserve the active connection draft. */}
- <Lazy key={config.id} config={config} visible={visible} showTechnicalSections={showTechnicalSections} onLeave={onLeave} />
+ <Lazy key={config.id} config={config} visible={visible} showTechnicalSections={showTechnicalSections} onLeave={onLeave} onOpen={onOpen} />
</Suspense>
);
};
diff --git a/client/src/components/credentials/ProviderPage.tsx b/client/src/components/credentials/ProviderPage.tsx
index 3afce0e3..f49ad63a 100644
--- a/client/src/components/credentials/ProviderPage.tsx
+++ b/client/src/components/credentials/ProviderPage.tsx
@@ -39,9 +39,12 @@ export interface ProviderPageProps {
showHeading?: boolean;
/** Move focus to Back when the page appears (it replaced the list). */
autoFocusBack?: boolean;
+ /** Show another provider's page (the MCP server card's page opens the
+ * connector it added), once the refetched catalogue holds it. */
+ onOpen?: (providerId: string) => void;
}
-export function ProviderPage({ view, selection, backLabel, onBack, visible, showHeading = false, autoFocusBack = false }: ProviderPageProps) {
+export function ProviderPage({ view, selection, backLabel, onBack, visible, showHeading = false, autoFocusBack = false, onOpen }: ProviderPageProps) {
const showTechnicalSections = useShellMode() === 'dev';
const provider = view.providers.find((p) => p.id === selection.id) ?? null;
const config = useMemo(() => (provider ? rehydrateProvider(provider) : null), [provider]);
@@ -106,7 +109,13 @@ export function ProviderPage({ view, selection, backLabel, onBack, visible, show
{provider.runs_locally && <span>Runs on this computer</span>}
</div>
</div>
- <PanelRenderer config={config} visible={visible} showTechnicalSections={showTechnicalSections} onLeave={onBack} />
+ <PanelRenderer
+ config={config}
+ visible={visible}
+ showTechnicalSections={showTechnicalSections}
+ onLeave={onBack}
+ onOpen={onOpen && ((id) => void view.refetch().then(() => onOpen(id)))}
+ />
</>
)}
</>
diff --git a/client/src/components/credentials/__tests__/CredentialsBrowser.test.tsx b/client/src/components/credentials/__tests__/CredentialsBrowser.test.tsx
index 4bf00e44..9e68f2bb 100644
--- a/client/src/components/credentials/__tests__/CredentialsBrowser.test.tsx
+++ b/client/src/components/credentials/__tests__/CredentialsBrowser.test.tsx
@@ -120,6 +120,19 @@ describe('CredentialsBrowser', () => {
expect(onConnect).not.toHaveBeenCalled();
});
+ it('lists the MCP server card under Custom, and its Connect opens its page', () => {
+ const MCP_SERVER: ConsumerProvider = {
+ id: 'mcp', name: 'MCP server', category: 'custom', category_label: 'Custom', consumer_category: 'custom',
+ color: '', kind: 'mcpAdd', connected: false, publisher: 'OpenCompany', verified: true,
+ description: 'Connect any MCP server: its tools become an app your employees can use.',
+ };
+ const onConnect = vi.fn();
+ render(<ThemeProvider><CredentialsBrowser catalogue={catalogue([ENDPOINT, MCP_SERVER])} onConnect={onConnect} /></ThemeProvider>);
+ expect(screen.getByText('Connect any MCP server: its tools become an app your employees can use.')).toBeInTheDocument();
+ fireEvent.click(screen.getByRole('button', { name: 'Connect MCP server' }));
+ expect(onConnect).toHaveBeenCalledWith('mcp', 'connect');
+ });
+
it('has no Add where the host turns custom connectors off', () => {
render(<ThemeProvider><CredentialsBrowser catalogue={catalogue()} onConnect={vi.fn()} customConnectors={false} /></ThemeProvider>);
expect(screen.queryByRole('button', { name: 'Add' })).not.toBeInTheDocument();
diff --git a/client/src/components/credentials/panels/McpAddPanel.tsx b/client/src/components/credentials/panels/McpAddPanel.tsx
new file mode 100644
index 00000000..a3417a29
--- /dev/null
+++ b/client/src/components/credentials/panels/McpAddPanel.tsx
@@ -0,0 +1,18 @@
+/**
+ * McpAddPanel — the MCP server card's page (kind `mcpAdd`): the custom
+ * connector form (AddConnectorForm), the same one the Connectors page's Add
+ * opens. A saved connector then shows on its own page (`onOpen`); Cancel,
+ * or an OAuth sign-in left to finish in its own tab, goes back to the list.
+ */
+
+import { AddConnectorForm } from '../AddConnectorForm';
+import type { CredentialPanelProps } from '../PanelRenderer';
+
+export default function McpAddPanel({ config, onLeave, onOpen }: CredentialPanelProps) {
+ return (
+ <div className="flex flex-col gap-4 p-5">
+ {config.instructions && <p className="m-0 text-sm text-muted-foreground">{config.instructions}</p>}
+ <AddConnectorForm close={() => onLeave?.()} onAdded={(ref) => onOpen?.(ref)} />
+ </div>
+ );
+}
diff --git a/client/src/components/credentials/panels/__tests__/McpAddPanel.test.tsx b/client/src/components/credentials/panels/__tests__/McpAddPanel.test.tsx
new file mode 100644
index 00000000..c3966636
--- /dev/null
+++ b/client/src/components/credentials/panels/__tests__/McpAddPanel.test.tsx
@@ -0,0 +1,83 @@
+import { beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
+import { fireEvent, render, screen, waitFor, within } from '@testing-library/react';
+import type { CredentialsCatalogue, ConsumerProvider } from '../../catalogue';
+
+const mocks = vi.hoisted(() => ({ sendRequest: vi.fn() }));
+vi.mock('@/contexts/WebSocketContext', () => ({
+ useWebSocketActions: () => ({ sendRequest: mocks.sendRequest, isReady: true }),
+ CREDENTIAL_PROBE_REQUEST_TIMEOUT: 60_000,
+}));
+vi.mock('@/app/ShellModeSwitch', () => ({ useShellMode: () => 'normal' }));
+vi.mock('sonner', () => ({ toast: { info: vi.fn(), success: vi.fn(), error: vi.fn() } }));
+
+import { ProviderPage } from '../../ProviderPage';
+
+// The page's panel loads lazily; importing it first keeps that import out of
+// the first test's wait.
+beforeAll(async () => {
+ await import('../McpAddPanel');
+});
+
+/** The MCP server card as the catalogue serves it (credential_providers.json `mcp`). */
+const MCP_SERVER: ConsumerProvider = {
+ id: 'mcp', name: 'MCP server', category: 'custom', category_label: 'Custom', consumer_category: 'custom',
+ color: '', kind: 'mcpAdd', icon_ref: 'lobehub:mcp', publisher: 'OpenCompany', verified: true,
+ stored: false, connected: false, fields: [],
+ description: 'Connect any MCP server: its tools become an app your employees can use.',
+ instructions: 'Give the address of a server that speaks MCP (the Model Context Protocol), and how it signs in.',
+};
+
+function mount() {
+ const refetch = vi.fn().mockResolvedValue({});
+ const view = {
+ catalogue: { data: { providers: [MCP_SERVER] } }, providers: [MCP_SERVER], categories: [],
+ isLoading: false, isError: false, error: null, refetch,
+ } as unknown as CredentialsCatalogue;
+ const onBack = vi.fn();
+ const onOpen = vi.fn();
+ render(
+ <ProviderPage view={view} selection={{ id: 'mcp', intent: 'connect' }} backLabel="All connectors" onBack={onBack} visible onOpen={onOpen} />,
+ );
+ return { refetch, onBack, onOpen };
+}
+
+beforeEach(() => {
+ mocks.sendRequest.mockReset();
+});
+
+describe('The MCP server card’s page', () => {
+ it('is the custom connector form, and opens the connector it added', async () => {
+ mocks.sendRequest.mockResolvedValue({ success: true, ref: 'mcp:orders' });
+ const { refetch, onBack, onOpen } = mount();
+ const form = within(await screen.findByRole('form', { name: 'Custom connector' }));
+ expect(screen.getByText(/Give the address of a server that speaks MCP/)).toBeInTheDocument();
+ fireEvent.change(form.getByLabelText('Server URL'), { target: { value: 'https://orders.example.com/mcp' } });
+ fireEvent.click(form.getByRole('button', { name: 'Add' }));
+ await waitFor(() => expect(onOpen).toHaveBeenCalledWith('mcp:orders'));
+ expect(mocks.sendRequest).toHaveBeenCalledWith(
+ 'mcp_connector_add',
+ { name: '', url: 'https://orders.example.com/mcp', sign_in: { kind: 'none' } },
+ 60_000,
+ );
+ // Its page opens once the catalogue holds it, straight from this one.
+ expect(refetch.mock.invocationCallOrder[0]).toBeLessThan(onOpen.mock.invocationCallOrder[0]);
+ expect(onBack).not.toHaveBeenCalled();
+ });
+
+ it('goes back to the list on Cancel, and when the sign-in goes on in its own tab', async () => {
+ const open = vi.spyOn(window, 'open').mockReturnValue(null);
+ mocks.sendRequest.mockResolvedValue({ success: true, ref: 'mcp:orders', sign_in_url: 'https://auth.example.com/authorize?state=s' });
+ const { onBack, onOpen } = mount();
+ const form = within(await screen.findByRole('form', { name: 'Custom connector' }));
+ fireEvent.click(form.getByRole('button', { name: 'Cancel' }));
+ expect(onBack).toHaveBeenCalledOnce();
+
+ fireEvent.change(form.getByLabelText('Server URL'), { target: { value: 'https://orders.example.com/mcp' } });
+ fireEvent.click(form.getByRole('radio', { name: 'OAuth' }));
+ fireEvent.click(form.getByRole('button', { name: 'Add' }));
+ await waitFor(() => expect(open).toHaveBeenCalledWith('https://auth.example.com/authorize?state=s', '_blank', 'noopener,noreferrer'));
+ expect(onBack).toHaveBeenCalledTimes(2);
+ expect(onOpen).not.toHaveBeenCalled();
+ open.mockRestore();
+ });
+});
diff --git a/client/src/components/credentials/types.ts b/client/src/components/credentials/types.ts
index 7e10d602..fee2e686 100644
--- a/client/src/components/credentials/types.ts
+++ b/client/src/components/credentials/types.ts
@@ -12,7 +12,7 @@ export type { ActionButtonIntent };
// Panel kinds — one renderer branch per kind
// ============================================================================
-export type PanelKind = 'apiKey' | 'oauth' | 'qrPairing' | 'email' | 'browserProfiles' | 'mcp';
+export type PanelKind = 'apiKey' | 'oauth' | 'qrPairing' | 'email' | 'browserProfiles' | 'mcp' | 'mcpAdd';
// ============================================================================
// Field schema — drives antd Form.Item rendering via FieldRenderer
diff --git a/client/src/hooks/useCatalogueQuery.ts b/client/src/hooks/useCatalogueQuery.ts
index 9715e699..242f274e 100644
--- a/client/src/hooks/useCatalogueQuery.ts
+++ b/client/src/hooks/useCatalogueQuery.ts
@@ -144,7 +144,7 @@ export interface ServerProviderConfig {
category: string;
category_label: string;
color: string;
- kind: 'apiKey' | 'oauth' | 'qrPairing' | 'email' | 'browserProfiles' | 'mcp';
+ kind: 'apiKey' | 'oauth' | 'qrPairing' | 'email' | 'browserProfiles' | 'mcp' | 'mcpAdd';
icon_ref?: string;
fields?: ServerFieldDef[];
ws?: { login: string; logout: string; status: string };
diff --git a/docs-internal/frontend_architecture.md b/docs-internal/frontend_architecture.md
index 572dcac4..ecf911ff 100644
--- a/docs-internal/frontend_architecture.md
+++ b/docs-internal/frontend_architecture.md
@@ -127,6 +127,7 @@ client/src/
│ │ │ ├── EmailPanel.tsx # IMAP/SMTP (RHF + zod)
│ │ │ ├── BrowserProfilesPanel.tsx # Web browser login profiles: list / add / delete, session-file import
│ │ │ ├── McpConnectorPanel.tsx # A custom MCP connector: Test, Refresh (a change waits for Accept), Remove, each tool's Use / Ask first
+│ │ │ ├── McpAddPanel.tsx # The MCP server card's page: the custom connector form, then the new connector's page (onOpen)
│ │ │ └── schemas/email.ts # Email zod schema w/ superRefine
│ │ ├── sections/
│ │ │ ├── ApiUsageSection.tsx # Per-service usage/cost
@@ -435,7 +436,7 @@ components/credentials/CredentialsModal.tsx (one AppShell host)
- `PanelRenderer` lazy-loads each panel type so the initial JS payload doesn't grow linearly with provider count.
- Panels are config-driven: `StatusCard`, `ActionBar`, `FieldRenderer`, `OAuthConnect` consume `ProviderConfig` fields rather than hand-coding per-provider JSX.
- Exception: EmailPanel has conditional `custom` IMAP/SMTP fields that the simple schema can't express — it gets a dedicated zod schema and RHF form. That's the boundary where config-driven hands off to hand-written.
-- Custom MCP connectors are cards the server builds, one per saved connector (`kind: 'mcp'`, with an `mcp` block: server, address, sign-in kind, tools, pending change). The browser's Add (`CatalogLayout.primaryAction`, off in the Welcome guide via `customConnectors={false}`) opens `AddConnectorForm`; after `mcp_connector_add` it refetches the catalogue, then opens the new card's page. `McpConnectorPanel` sends each command with `CREDENTIAL_PROBE_REQUEST_TIMEOUT` and waits for the refetched catalogue before re-enabling, so it shows only what the server holds; Remove leaves the page through the panel's `onLeave` (ProviderPage's Back). See [MCP Connectors](./mcp_connectors.md).
+- Custom MCP connectors are cards the server builds, one per saved connector (`kind: 'mcp'`, with an `mcp` block: server, address, sign-in kind, tools, pending change). The browser's Add (`CatalogLayout.primaryAction`, off in the Welcome guide via `customConnectors={false}`) opens `AddConnectorForm`; after `mcp_connector_add` it refetches the catalogue, then opens the new card's page. The same form is the page of the MCP server card (`mcp` in `credential_providers.json`, `kind: 'mcpAdd'`, Custom category, never connected itself): `McpAddPanel` hands the saved connector to the host through the panel's `onOpen`, and ProviderPage opens its page once the refetched catalogue holds it (the credentials dialog passes `onOpen`). `McpConnectorPanel` sends each command with `CREDENTIAL_PROBE_REQUEST_TIMEOUT` and waits for the refetched catalogue before re-enabling, so it shows only what the server holds; Remove leaves the page through the panel's `onLeave` (ProviderPage's Back). See [MCP Connectors](./mcp_connectors.md).
## ParameterRenderer (pending Phase 6)
diff --git a/docs-internal/mcp_connectors.md b/docs-internal/mcp_connectors.md
index 13a74d26..e33dfdf9 100644
--- a/docs-internal/mcp_connectors.md
+++ b/docs-internal/mcp_connectors.md
@@ -1,8 +1,9 @@
# MCP Connectors
The owner connects OpenCompany to an outside MCP server from Connectors →
-**Add**: its URL, a name, and how it signs in. Each saved connector is its own
-card on the Connectors page, and its tools are what that server offers.
+**Add**, or from the **MCP server** card (Custom category), whose page is the
+same form: its URL, a name, and how it signs in. Each saved connector is its
+own card on the Connectors page, and its tools are what that server offers.
Here OpenCompany is the MCP **client**. The opposite direction, where CLI
agents call into OpenCompany's own MCP server (`/mcp/ide`), is a separate
@@ -22,6 +23,7 @@ thing: see [CLI Agent Framework](./cli_agent_framework.md).
| The outbound address rules, shared with the Browser node | `server/services/netpolicy.py` |
| The cards' shared fields, and the `custom` categories | `server/config/credential_providers.json` (`_mcp_connector`) |
| The Add form | `client/src/components/credentials/AddConnectorForm.tsx` |
+| The MCP server card's page (the same form) | `client/src/components/credentials/panels/McpAddPanel.tsx` |
| A connector's page | `client/src/components/credentials/panels/McpConnectorPanel.tsx` |
| The card's wire type | `ServerMcpConnector` in `client/src/hooks/useCatalogueQuery.ts` |
@@ -116,6 +118,15 @@ card per saved connector from the `_mcp_connector` template
No secret is ever on the card.
+The **MCP server** card is where one is added: a static provider, `mcp` in
+`credential_providers.json`, with `kind` `mcpAdd`, `consumer_category`
+`custom`, the MCP logo (`lobehub:mcp`), and no fields. It is never connected
+itself (no rule makes it `stored`). Its page (`panels/McpAddPanel.tsx`) is the
+custom connector form. A saved connector's page then opens through the
+panel's `onOpen`: ProviderPage refetches the catalogue first, then the
+credentials dialog shows it. Cancel, or an OAuth sign-in that goes on in its
+own tab, goes back to the list.
+
## Commands
All are `@ws_response`. They are refused from `/ws/internal`. Each change is
diff --git a/server/config/credential_providers.json b/server/config/credential_providers.json
index 27314209..2ffecf5e 100644
--- a/server/config/credential_providers.json
+++ b/server/config/credential_providers.json
@@ -408,6 +408,21 @@
"fields": [],
"instructions": "A connection you added to an MCP server: its tools are what the server offers. Test checks that it still answers. Refresh reads its tools again and shows any change for you to accept before an employee can use it."
},
+ "mcp": {
+ "_description": "The MCP server card, where a custom connector is added: its page is the custom connector form (kind mcpAdd, panels/McpAddPanel.tsx), the same form the Connectors page's Add opens. It is never connected itself: each saved connector is its own card, mcp:<slug>, from the _mcp_connector template above.",
+ "name": "MCP server",
+ "publisher": "OpenCompany",
+ "verified": true,
+ "consumer_category": "custom",
+ "description": "Connect any MCP server: its tools become an app your employees can use.",
+ "category": "custom",
+ "category_label": "Custom",
+ "color": "dracula.cyan",
+ "kind": "mcpAdd",
+ "icon_ref": "lobehub:mcp",
+ "fields": [],
+ "instructions": "Give the address of a server that speaks MCP (the Model Context Protocol), and how it signs in. Its tools are read before anything is kept. Each tool asks you before it runs unless the server marks it read-only, and you can turn any of them off."
+ },
"_cli_base": {
"_abstract": true,
"category": "ai",
diff --git a/server/nodes/mcp/_credentials.py b/server/nodes/mcp/_credentials.py
index 693f18af..ad2b1102 100644
--- a/server/nodes/mcp/_credentials.py
+++ b/server/nodes/mcp/_credentials.py
@@ -1,9 +1,10 @@
-"""Custom connectors in the credentials catalogue: no card of their own, one
-card per saved connector (``catalogue_entries``), built from the
-``_mcp_connector`` template in config/credential_providers.json and what was
-saved (``_store.py``). Each card is ``kind: "mcp"`` and carries ``mcp``: the
-server's address without credentials, how it signs in, the server's name,
-its tools with the owner's settings, and what a refresh found.
+"""Custom connectors in the credentials catalogue: the MCP server card, where
+one is added (``mcp`` in config/credential_providers.json, ``kind:
+"mcpAdd"``, never connected itself), and one card per saved connector
+(``catalogue_entries``), built from the ``_mcp_connector`` template there and
+what was saved (``_store.py``). Each saved one is ``kind: "mcp"`` and carries
+``mcp``: the server's address without credentials, how it signs in, the
+server's name, its tools with the owner's settings, and what a refresh found.
"""
from __future__ import annotations
diff --git a/server/tests/nodes/test_mcp_connector.py b/server/tests/nodes/test_mcp_connector.py
index 1b0a395f..347cd5ff 100644
--- a/server/tests/nodes/test_mcp_connector.py
+++ b/server/tests/nodes/test_mcp_connector.py
@@ -213,6 +213,17 @@ def test_a_key_in_the_urls_path_is_never_kept_in_plain_text():
assert "tok-123" not in json.dumps(meta) and "q-456" not in json.dumps(meta)
+async def test_the_mcp_server_card_is_where_one_is_added_and_is_never_connected(auth):
+ from services.credential_registry import get_credential_registry, provider_connection_state
+
+ [card] = [provider for provider in get_credential_registry().get_catalogue()["providers"] if provider["id"] == "mcp"]
+ assert (card["name"], card["kind"], card["consumer_category"], card["icon_ref"]) == ("MCP server", "mcpAdd", "custom", "lobehub:mcp")
+ assert card["fields"] == []
+ # Saved connectors are their own cards; this one only adds them.
+ state = await provider_connection_state(card, auth)
+ assert (state["stored"], state["connected"]) == (False, False)
+
+
def test_a_slug_starts_with_a_letter_as_a_tool_name_must():
assert new_slug("Orders", URL) == "orders"
assert new_slug("", URL) == "mcp-127-0-0-1"