add-remote-mcp

Add Remote MCP

Generate skills from public or simply-authenticated remote MCP servers using the framework's shared plaited/mcp library surface.

Remote MCP URLs often start as discovery URLs that also accept Streamable HTTP MCP traffic. For example, https://bun.com/docs/mcp is a valid remote MCP URL for discovery, tool listing, and direct tool calls.

When to use

• Adding a new remote MCP server as a searchable skill
• Discovering what tools, prompts, and resources an MCP server exposes
• Generating typed wrapper scripts for MCP tools
• Evaluating MCP prompts for adaptation into skill instructions
• Downloading or scripting access to MCP resources
• Working with public endpoints or simple header-auth servers

Use add-protected-remote-mcp instead when the server needs OAuth, rotated refresh material, or a generic tool-execution wrapper that should resolve secrets from env or Varlock without checked-in tokens.

URL shapes

Remote MCP integrations commonly begin from one of two URL types:

• Discovery/manifest URL — Returns advertised capabilities as JSON. Example: https://bun.com/docs/mcp
• Live transport endpoint — Supports Streamable HTTP MCP session traffic directly.

The shared plaited/mcp library accepts either URL type:

• mcpDiscover, mcpListTools, mcpListPrompts, mcpListResources
  • accept either URL type
• createRemoteMcpSession, remoteMcpConnect, mcpCallTool, mcpGetPrompt, mcpReadResource
  • work against live transport endpoints and manifest URLs that also serve Streamable HTTP

If you only have a discovery URL, start by trying it directly. If connection attempts fail, then fall back to discovery/list wrappers or use the advertised capabilities to locate a separate transport endpoint.

Discovery

• Unified CLI for discovery, listing, prompt fetches, resource reads, and session summaries: bun skills/add-remote-mcp/scripts/run.ts '{"url":"https://bun.com/docs/mcp","operation":{"type":"session-summary"}}'
• Full capability discovery and tool listing: references/discovery-template.ts
• Prompt retrieval: references/prompt-template.ts
• Resource reads: references/resource-template.ts

Session API (connection reuse)

For multiple operations against the same server, use a session when the URL accepts live MCP traffic. See references/session-template.ts.

await using automatically closes the connection when the block exits.

Skill Generation Pattern

After discovery, evaluate each capability type and generate the appropriate skill structure.

1. Tools → scripts/

Tools become executable wrapper scripts. Use references/wrapper-template.ts as a starting point:

mkdir -p skills/search-my-service/scripts
cp skills/add-remote-mcp/references/wrapper-template.ts skills/search-my-service/scripts/search.ts

Edit the constants: MCP_URL, TOOL_NAME, and adjust the input validation if the tool takes more than query.

Start with the discovery URL the server publishes. If direct execution fails, switch the wrapper to the server's separate transport URL if one is advertised.

2. Prompts → evaluate for skill adaptation

MCP prompts are pre-built message templates. Evaluate whether to:

• Adapt into SKILL.md instructions — If the prompt teaches a workflow, extract its content into the skill's markdown body.
• Create a prompt script in scripts/ — If the prompt is used at runtime. See references/prompt-template.ts.

3. Resources → assets/ or pull scripts

• Static/small → assets/ — Download once and commit.
• Dynamic/large → scripts/ — Fetch on demand. See references/resource-template.ts.

4. Scaffold SKILL.md

Create skills/my-skill/SKILL.md with frontmatter:

---
name: my-skill
description: What this skill does. Use when...
license: ISC
compatibility: Requires bun and network access
allowed-tools: Bash
---

5. Validate

# Check the generated skill against the AgentSkills spec and repo conventions
bun run skills/search-agent-skills/scripts/search.ts '{"query":"SKILL.md frontmatter fields scripts references assets conventions"}'

# Or inspect the remote server directly through the unified add-remote-mcp CLI
bun skills/add-remote-mcp/scripts/run.ts '{"url":"https://bun.com/docs/mcp","operation":{"type":"session-summary"}}'

6. Test

bun run skills/my-skill/scripts/search.ts '{"query": "test query"}'

Authentication

Tier 1: No auth (public endpoints)

No options needed — the default:

const tools = await mcpListTools('https://bun.com/docs/mcp')

Tier 2: API key / Bearer token

Pass custom headers via options. See references/wrapper-template.ts.

Which tier to use

Scenario	Tier	Example
Public doc search	No auth	modelcontextprotocol.io, agentskills.io
SaaS API with API key	Bearer token	You.com, OpenAI
Enterprise SSO / IdP	Use add-protected-remote-mcp	Internal services
Agent-to-agent (Modnet)	Use add-protected-remote-mcp	Node MCP servers

No secrets in repo

• Do not commit JWTs, access tokens, refresh tokens, or client secrets into tracked files.
• Checked-in config for simple auth may include header names and env var names, but the secret values themselves must come from env or Varlock-injected env vars.

References

• references/discovery-template.ts — Capability discovery and tool listing
• references/session-template.ts — Reusable remote session pattern
• references/prompt-template.ts — Prompt retrieval example
• references/resource-template.ts — Resource read example
• references/wrapper-template.ts — Template for MCP wrapper scripts that import plaited/mcp

Dependencies

• @modelcontextprotocol/sdk — MCP protocol client (Streamable HTTP transport)

Protocol notes

• Discovery/list helpers accept both manifest URLs and live Streamable HTTP transport URLs
• Session-style APIs also work with manifest URLs when the same URL serves live MCP traffic
• Uses MCP Streamable HTTP transport (2025-03-26+) via StreamableHTTPClientTransport
• SDK handles Accept header negotiation (application/json and text/event-stream)
• Session API reuses a single connection; one-shot helpers create and dispose per call
• Not for stdio-based MCP servers — use add-mcp directly with an stdio transport