Guide / artifact / MCP

MCP artifact: connect a tool server

Use an MCP artifact when the release configures a server that an AI tool can call over stdio or HTTP.

When to use MCP

Choose MCP when the main payload is a server connection, not a markdown instruction file. HubBound writes a provider-compatible MCP entry and keeps ownership metadata so uninstall can remove only what HubBound owns.

MCP content is interpreted directly; it does not need an entrypoint markdown file. The deployment still needs at least one safe matching files pattern, so include a small README.md or other package documentation in the snapshot.

The content props

content must be a JSON object matching the MCP config. Keep secrets as references, never literal tokens. Transport type controls whether providers receive a command-based stdio server or a URL-based HTTP server.

id Stable server identifier. If present, HubBound uses it to derive the provider-side name; otherwise it derives one from the artifact name.
enabled Whether the generated server entry starts enabled.
transport.type Use stdio, http, streamable_http or streamable-http according to the server. sse is also understood by Copilot's native MCP shape.
transport.command / args Command and ordered arguments for a stdio server.
transport.url / headers URL and optional headers for HTTP. Put secret references in header values, not secret literals.
transport.env / cwd Environment references and working directory for stdio.
secrets Metadata for required user inputs: label, type, required, description and placeholder.
permissions Optional tools.allow, tools.deny and confirm arrays. Codex uses allow/deny to shape enabled/disabled tools.

A complete deployment

The example uses stdio. For HTTP, replace command/args with url and headers. The README keeps the required files snapshot useful without becoming runtime configuration.

{
  "kind": "artifact",
  "path": "packages/docs-search",
  "tag": "vendor/docs-search",
  "version": "1.0.0",
  "visibility": "org",
  "artifact_type": "MCP",
  "description": "Search the internal documentation index",
  "content": {
    "id": "docs-search",
    "enabled": true,
    "transport": {
      "type": "stdio",
      "command": "node",
      "args": ["server.js"],
      "cwd": ".",
      "env": { "DOCS_TOKEN": "{{secrets.DOCS_TOKEN}}" }
    },
    "secrets": {
      "DOCS_TOKEN": {
        "label": "Documentation token",
        "type": "secret",
        "required": true,
        "placeholder": "Paste your token"
      }
    },
    "permissions": {
      "tools": { "allow": ["search"], "deny": ["delete"] },
      "confirm": ["reindex"]
    }
  },
  "files": ["README.md", "server.js"]
}

Check before deploy

Validate JSON syntax, confirm every secret reference is intentional, and run the dry-run. At install time providers receive environment references rather than literal secret values; users still need to supply the referenced secret in their environment or provider setup.

  • Do not put tokens in content, files, git history or descriptions.
  • Make the command executable and test it independently before packaging.
  • Use an exact version and bump it for a changed server contract.
  • If a provider does not support a permission shape, its applicator may omit that optional field; test the target provider after install.
Deploy guide