Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.pluxx.dev/llms.txt

Use this file to discover all available pages before exploring further.

This workflow creates the deterministic first scaffold from a raw MCP source. Use it when you want to:
  • inspect a live MCP surface
  • import an MCP that is already configured in a local host
  • generate a Pluxx source project
  • validate the baseline before any agent-driven refinement
This flow does not invoke Claude Code, Codex, Cursor, or OpenCode. It is the model-free import layer. 
npx @orchid-labs/pluxx init --from-mcp https://example.com/mcp --yes
npx @orchid-labs/pluxx doctor
npx @orchid-labs/pluxx lint
npx @orchid-labs/pluxx eval
npx @orchid-labs/pluxx test
What each step does:
  • init: introspects the MCP and writes the source project
  • doctor: checks the scaffold and runtime assumptions
  • lint: checks platform rules and structural quality
  • eval: checks scaffold and prompt-pack quality
  • test: runs the end-to-end verification contract

​
Source shapes

Remote HTTP MCP: 
npx @orchid-labs/pluxx init --from-mcp https://example.com/mcp --yes
Remote HTTP MCP with preapproved tool access: 
npx @orchid-labs/pluxx init --from-mcp https://example.com/mcp --yes --approve-mcp-tools
Local stdio MCP: 
npx @orchid-labs/pluxx init --from-mcp "npx -y -p @acme/mcp acme-mcp" --yes
For local stdio imports, pass the real executable command. Do not assume the npm package name is also the runnable bin name. Examples:
  • installed locally: npx @orchid-labs/pluxx init --from-mcp "./node_modules/.bin/acme-mcp" --yes
  • one-shot via npm: npx @orchid-labs/pluxx init --from-mcp "npx -y -p @acme/mcp acme-mcp" --yes
Legacy SSE MCP: 
npx @orchid-labs/pluxx init --from-mcp https://example.com/sse --transport sse --yes
Already-installed MCP config: 
npx @orchid-labs/pluxx discover-mcp
npx @orchid-labs/pluxx init --from-installed-mcp codex:acme --yes
discover-mcp reads common Claude Code, Cursor, Codex, and OpenCode config locations. The import normalizes env/auth references without copying literal secret values into the generated project.

​
What gets generated

The first pass creates a maintained source project, typically including: 
my-plugin/
  pluxx.config.ts
  INSTRUCTIONS.md
  skills/
  commands/
  scripts/
  .pluxx/
    mcp.json
    taxonomy.json
Keep editing the source project. Treat dist/ as generated output after pluxx build. For local stdio MCPs, the current import and validation path also checks whether project-relative runtime files are bundled. Pluxx can infer passthrough for common project-relative runtime paths, warns when installed .mcp.json files would point at missing payloads, and smoke-launches installed stdio MCP commands during consumer-side verification.

​
Auth examples

Bearer: 
npx @orchid-labs/pluxx init --from-mcp https://example.com/mcp --yes --auth-env API_KEY --auth-type bearer
Custom header: 
npx @orchid-labs/pluxx init \
  --from-mcp https://mcp.playkit.sh/mcp \
  --yes \
  --auth-env PLAYKIT_API_KEY \
  --auth-type header \
  --auth-header X-API-Key \
  --auth-template '${value}'
OAuth-first MCPs can still be scaffolded, but the import path matters:
  • if the provider exposes a usable token or API key, pass it with --auth-env
  • if the provider only supports browser-interactive auth during handshake, use --oauth-wrapper
  • if runtime auth should be host-managed, use --runtime-auth platform
If the MCP is already trusted and you want the generated scaffold to start with broad MCP tool approval, add:
  • --approve-mcp-tools
That emits canonical permission intent into pluxx.config.ts as:
  • permissions.allow = ["MCP(<server>.*)"]
If you also have a product website or docs, you can seed sourced context during the deterministic import itself: 
npx @orchid-labs/pluxx init --from-mcp https://example.com/mcp \
  --yes \
  --website https://example.com \
  --docs https://docs.example.com/mcp \
  --ingest-provider auto
That writes:
  • .pluxx/sources.json
  • .pluxx/docs-context.json
and uses those sourced signals to improve the first-pass scaffold before you move into Agent Mode.

​
When to bring in the agent layer

After this deterministic import flow passes, you can optionally move into:
  • pluxx agent prepare
  • pluxx agent run taxonomy ...
  • pluxx agent run instructions ...
  • pluxx autopilot ...
Use that second stage when the scaffold is valid but still too tool-shaped, too generic, or too weak in its instructions. For a complete end-to-end flow, see Create a Pluxx plugin.