Skip to content
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 32 additions & 5 deletions docs/use/connect-your-agent.md
Original file line number Diff line number Diff line change
@@ -1,13 +1,17 @@
# Connect your agent

Kody is an MCP server. You use it from Cursor, Claude Desktop, or any other AI
agent that supports MCP — not from a separate Kody chat app.
Kody is an MCP server. You use it from Cursor, Claude Desktop, Claude Code,
Codex / ChatGPT, OpenCode, VS Code, or any other AI agent that supports MCP —
not from a separate Kody chat app.

The in-app Get started page (`/onboarding`) has tabs with client-specific
instructions and copyable config snippets for the host you are on.

## Add the MCP server

1. In your agent host, add a remote MCP server.
2. Use this deployment’s MCP URL: `https://<this-host>/mcp`. The in-app Get
started page (`/onboarding`) shows the exact URL for the host you are on.
1. Open Get started (`/onboarding`) and choose your client tab, or follow the
short notes below.
2. Use this deployment’s MCP URL: `https://<this-host>/mcp`.
3. Complete the OAuth flow when the host opens it. Sign in to Kody if needed,
then approve access.

Expand All @@ -18,6 +22,29 @@ restart the host connection. Unverified visits to Get started (`/onboarding`)
redirect to `/pending-verification`; after verification, onboarding shows the
MCP URL and setup prompt.

### Client notes

- **Cursor** — Add a remote MCP server from Customize, or merge a
`mcpServers.kody.url` entry into `~/.cursor/mcp.json` / `.cursor/mcp.json`.
- **Claude Desktop** — Use Settings → Connectors (custom connector + MCP URL).
Remote servers are not configured through `claude_desktop_config.json`.
- **Claude Code** — `claude mcp add --transport http -s user kody <url>`, or a
`.mcp.json` entry with `"type": "http"`.
- **Codex / ChatGPT** — ChatGPT web uses Developer mode + a connector/app URL.
Codex (desktop, CLI, IDE) shares `~/.codex/config.toml` with an
`[mcp_servers.kody]` `url` entry.
- **OpenCode** — Add a `mcp.kody` remote entry in `opencode.json`
(`"type": "remote"`).
- **VS Code** — Use `.vscode/mcp.json` with root key `servers` (not
`mcpServers`) and `"type": "http"`.

### Coding vs non-coding agents

Using Kody packages works great with non-coding agents such as Claude Desktop
and ChatGPT. For creating or editing packages, a coding agent (Cursor, Claude
Code, Codex, VS Code, OpenCode, and similar) is usually smoother because those
hosts can edit files and iterate on code more easily.

## Ask your agent to help set up

After the connection works, paste a short setup prompt into your agent (the Get
Expand Down
230 changes: 230 additions & 0 deletions packages/worker/client/routes/onboarding-mcp-client-tabs.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,230 @@
import { type Handle, css } from 'remix/ui'
import { Tab, TabList, TabPanel, Tabs } from 'remix/ui/tabs'
import { CopyTextButton } from '#client/copy-text-button.tsx'
import {
buildClaudeCodeAddCommand,
buildClaudeCodeMcpJson,
buildCodexMcpToml,
buildCursorMcpJson,
buildOpenCodeMcpJson,
buildVsCodeMcpJson,
codingAgentPackageHint,
mcpClientTabs,
nonCodingAgentNote,
} from '#client/routes/onboarding-mcp-clients.ts'
import { colors, spacing, typography } from '#client/styles/tokens.ts'
import {
descriptionCss,
insetCardCss,
} from '#client/styles/style-primitives.ts'

type OnboardingMcpClientTabsProps = {
mcpServerUrl: string
}

function ConfigSnippet(handle: Handle<{ value: string; idleLabel: string }>) {
return () => (
<div mix={css(snippetWrapCss)}>
<pre mix={css(codeBlockCss)}>{handle.props.value}</pre>
<CopyTextButton
value={handle.props.value}
idleLabel={handle.props.idleLabel}
variant="secondary"
/>
</div>
)
}

function ClientNote(handle: Handle<{ children: string }>) {
return () => (
<p mix={css(noteCss)} role="note">
{handle.props.children}
</p>
)
}

export function OnboardingMcpClientTabs(
handle: Handle<OnboardingMcpClientTabsProps>,
) {
return () => {
const mcpServerUrl = handle.props.mcpServerUrl
const cursorJson = buildCursorMcpJson(mcpServerUrl)
const claudeCodeJson = buildClaudeCodeMcpJson(mcpServerUrl)
const claudeCodeCommand = buildClaudeCodeAddCommand(mcpServerUrl)
const vsCodeJson = buildVsCodeMcpJson(mcpServerUrl)
const openCodeJson = buildOpenCodeMcpJson(mcpServerUrl)
const codexToml = buildCodexMcpToml(mcpServerUrl)

return (
<Tabs defaultActiveTab="cursor">
<TabList aria-label="MCP client setup instructions">
{mcpClientTabs.map((tab) => (
<Tab name={tab.id}>{tab.label}</Tab>
))}
Comment on lines +61 to +63

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Add a key prop to the mapped Tab components.

React requires a key prop when rendering arrays of elements to properly track them during reconciliation.

♻️ Proposed fix
 					{mcpClientTabs.map((tab) => (
-						<Tab name={tab.id}>{tab.label}</Tab>
+						<Tab key={tab.id} name={tab.id}>{tab.label}</Tab>
 					))}
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
{mcpClientTabs.map((tab) => (
<Tab name={tab.id}>{tab.label}</Tab>
))}
{mcpClientTabs.map((tab) => (
<Tab key={tab.id} name={tab.id}>{tab.label}</Tab>
))}
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/worker/client/routes/onboarding-mcp-client-tabs.tsx` around lines 61
- 63, Update the mcpClientTabs.map rendering to add a stable key prop to each
Tab, using the existing tab.id identifier, while preserving the current name and
label props.

</TabList>

<TabPanel name="cursor">
<p mix={css(descriptionCss)}>
In Cursor, open <strong>Customize</strong> and add a remote MCP
server with this URL, or merge the JSON below into{' '}
<code>~/.cursor/mcp.json</code> (global) or{' '}
<code>.cursor/mcp.json</code> (project).
</p>
<pre mix={css(codeBlockCss)}>{mcpServerUrl}</pre>
<div mix={css(buttonRowCss)}>
<CopyTextButton
value={mcpServerUrl}
idleLabel="Copy MCP URL"
variant="primary"
/>
</div>
<p mix={css(descriptionCss)}>
JSON config (merge under your existing <code>mcpServers</code> if
you already have one):
</p>
<ConfigSnippet value={cursorJson} idleLabel="Copy JSON" />
<ClientNote>{codingAgentPackageHint}</ClientNote>
</TabPanel>

<TabPanel name="codex-chatgpt">
<p mix={css(descriptionCss)}>
<strong>ChatGPT (web)</strong>: turn on Developer mode under
Settings → Security and login, then create a developer-mode app /
connector pointed at the MCP URL below. Complete OAuth when
prompted.
</p>
<pre mix={css(codeBlockCss)}>{mcpServerUrl}</pre>
<div mix={css(buttonRowCss)}>
<CopyTextButton
value={mcpServerUrl}
idleLabel="Copy MCP URL"
variant="primary"
/>
</div>
<ClientNote>{nonCodingAgentNote}</ClientNote>
<p mix={css(descriptionCss)}>
<strong>Codex</strong> (ChatGPT desktop, Codex CLI, and the IDE
extension) share <code>~/.codex/config.toml</code>. Add this
streamable HTTP entry, then run <code>codex mcp login kody</code> if
OAuth does not start automatically:
</p>
<ConfigSnippet value={codexToml} idleLabel="Copy TOML" />
</TabPanel>

<TabPanel name="claude-desktop">
<p mix={css(descriptionCss)}>
In Claude Desktop, open <strong>Settings → Connectors</strong> (or
Customize → Connectors), add a custom connector, and paste this MCP
URL. Claude Desktop handles remote OAuth through that UI — do not
put the remote URL into <code>claude_desktop_config.json</code>.
</p>
<pre mix={css(codeBlockCss)}>{mcpServerUrl}</pre>
<div mix={css(buttonRowCss)}>
<CopyTextButton
value={mcpServerUrl}
idleLabel="Copy MCP URL"
variant="primary"
/>
</div>
<ClientNote>{nonCodingAgentNote}</ClientNote>
</TabPanel>

<TabPanel name="claude-code">
<p mix={css(descriptionCss)}>
Prefer the CLI (user scope, all projects):
</p>
<ConfigSnippet value={claudeCodeCommand} idleLabel="Copy command" />
<p mix={css(descriptionCss)}>
Or merge this into a project <code>.mcp.json</code> (or the
user-scoped <code>mcpServers</code> block). Claude Code requires{' '}
<code>type: &quot;http&quot;</code> for remote servers:
</p>
<ConfigSnippet value={claudeCodeJson} idleLabel="Copy JSON" />
<ClientNote>{codingAgentPackageHint}</ClientNote>
</TabPanel>

<TabPanel name="opencode">
<p mix={css(descriptionCss)}>
Add this to your OpenCode config (<code>opencode.json</code> in the
project, or your global OpenCode config). OpenCode uses{' '}
<code>type: &quot;remote&quot;</code> and will start OAuth when
needed:
</p>
<ConfigSnippet value={openCodeJson} idleLabel="Copy JSON" />
<p mix={css(descriptionCss)}>
You can also run <code>opencode mcp add</code> and paste the URL
interactively, then <code>opencode mcp auth kody</code> if prompted.
</p>
<ClientNote>{codingAgentPackageHint}</ClientNote>
</TabPanel>

<TabPanel name="vscode">
<p mix={css(descriptionCss)}>
Create or edit <code>.vscode/mcp.json</code> in your workspace (or
open user MCP config via the{' '}
<strong>MCP: Open User Configuration</strong> command). VS Code uses
the root key <code>servers</code>, not <code>mcpServers</code>:
</p>
<ConfigSnippet value={vsCodeJson} idleLabel="Copy JSON" />
<p mix={css(descriptionCss)}>
Use Agent mode in Copilot Chat so MCP tools are available, then
complete OAuth when VS Code opens it.
</p>
<ClientNote>{codingAgentPackageHint}</ClientNote>
</TabPanel>

<TabPanel name="other">
<p mix={css(descriptionCss)}>
Any MCP-capable host that supports remote / streamable HTTP servers
can connect to Kody. Add a remote MCP server pointed at this URL and
complete the OAuth flow when the host opens it:
</p>
<pre mix={css(codeBlockCss)}>{mcpServerUrl}</pre>
<div mix={css(buttonRowCss)}>
<CopyTextButton
value={mcpServerUrl}
idleLabel="Copy MCP URL"
variant="primary"
/>
</div>
<p mix={css(descriptionCss)}>
Config file shapes differ by host. If your client expects a JSON{' '}
<code>mcpServers</code> map with a <code>url</code> field, start
from the Cursor snippet; if it uses <code>servers</code> with{' '}
<code>type: &quot;http&quot;</code>, use the VS Code snippet.
</p>
</TabPanel>
</Tabs>
)
}
}

const codeBlockCss = {
...insetCardCss,
margin: 0,
whiteSpace: 'pre-wrap' as const,
wordBreak: 'break-word' as const,
fontFamily: typography.fontFamily,
fontSize: typography.fontSize.sm,
lineHeight: 1.6,
}

const snippetWrapCss = {
display: 'grid',
gap: spacing.sm,
}

const buttonRowCss = {
display: 'flex',
gap: spacing.sm,
flexWrap: 'wrap' as const,
}

const noteCss = {
...descriptionCss,
margin: 0,
padding: spacing.md,
borderRadius: 'var(--radius-md)',
border: `1px solid ${colors.border}`,
background: colors.primarySoftest,
}
82 changes: 82 additions & 0 deletions packages/worker/client/routes/onboarding-mcp-clients.node.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
import { expect, test } from 'vitest'
import {
buildClaudeCodeAddCommand,
buildClaudeCodeMcpJson,
buildCodexMcpToml,
buildCursorMcpJson,
buildOpenCodeMcpJson,
buildVsCodeMcpJson,
mcpClientTabs,
nonCodingAgentNote,
} from './onboarding-mcp-clients.ts'

const mcpServerUrl = 'https://heykody.dev/mcp'

test('mcp client tabs cover the popular hosts from onboarding', () => {
expect(mcpClientTabs.map((tab) => tab.id)).toEqual([
'cursor',
'codex-chatgpt',
'claude-desktop',
'claude-code',
'opencode',
'vscode',
'other',
])
expect(
mcpClientTabs.filter((tab) => tab.isNonCodingAgent).map((tab) => tab.id),
).toEqual(['codex-chatgpt', 'claude-desktop'])
expect(nonCodingAgentNote).toMatch(/coding agent/i)
})

test('Cursor JSON uses mcpServers with a remote url', () => {
expect(JSON.parse(buildCursorMcpJson(mcpServerUrl))).toEqual({
mcpServers: {
kody: {
url: mcpServerUrl,
},
},
})
})

test('Claude Code JSON requires type http for remote servers', () => {
expect(JSON.parse(buildClaudeCodeMcpJson(mcpServerUrl))).toEqual({
mcpServers: {
kody: {
type: 'http',
url: mcpServerUrl,
},
},
})
expect(buildClaudeCodeAddCommand(mcpServerUrl)).toBe(
`claude mcp add --transport http -s user kody ${mcpServerUrl}`,
)
})

test('VS Code JSON uses servers root key with type http', () => {
expect(JSON.parse(buildVsCodeMcpJson(mcpServerUrl))).toEqual({
servers: {
kody: {
type: 'http',
url: mcpServerUrl,
},
},
})
})

test('OpenCode JSON uses mcp remote type', () => {
expect(JSON.parse(buildOpenCodeMcpJson(mcpServerUrl))).toEqual({
mcp: {
kody: {
type: 'remote',
url: mcpServerUrl,
enabled: true,
},
},
})
})

test('Codex TOML is a streamable HTTP mcp_servers entry', () => {
expect(buildCodexMcpToml(mcpServerUrl)).toBe(
['[mcp_servers.kody]', `url = "${mcpServerUrl}"`, ''].join('\n'),
)
})
Loading
Loading