Automation and agents

MCP server

Serve typed Blob Yard tools to a local AI client from the signed CLI.

Before you start

Choose MCP for a local approved CLI session or create a scoped API token for unattended direct API access.
Keep the agent host and its secret store under your control.

Start the server

local MCP server

blobyard mcp serve --stdio

The MCP server is part of the native binary. It reuses the browser-approved CLI session and typed API client, writes protocol messages only to standard output, and keeps redacted diagnostics on standard error.

Connect a host

MCP host configuration

{
  "mcpServers": {
    "blobyard": {
      "command": "blobyard",
      "args": ["mcp", "serve", "--stdio"]
    }
  }
}

Any MCP host that launches stdio servers can use this configuration. Every tool call accepts an optional workspace and project scope that overrides the configured defaults for that call only.

Know the tool surface

Identity and structure: inspect identity, list or create workspaces and projects, rename a workspace, and list objects.
Transfer: upload file, download file, delete object.
Handoffs: create and list shares, previews, and inboxes, and revoke each.
Retention: read, set, clear, and inspect execution state for the project policy.
Web Yards: deploy static output, list Yards and deploy history, roll back, and delete.
Workspace administration: read audit events, manage members and invitations, and manage GitHub Actions OIDC trusts.
Credential metadata: list or revoke API tokens, and list or revoke browser-approved CLI sessions.
Billing and account state: inspect billing, request or inspect an account export, and inspect account deletion state.

The generated contract maps 52 public HTTP operations into 46 MCP tools. Upload and Web Yard deployment each combine several HTTP steps into one agent operation. Destructive tools require explicit confirmation where the MCP contract marks it, and share, preview, and inbox URLs are returned only by the matching create tool that issued them.

Keep one-time material out of MCP

Authentication start, refresh, logout, and GitHub OIDC assertion exchange stay with the CLI host or CI runner.
API-token creation is excluded because it returns a new bearer credential once.
Checkout, billing portal, plan update, and storage billing sessions are excluded because they return hosted Stripe capability URLs.
Account export download is excluded because it returns a signed URL.
Account deletion prepare, completion, and destructive retry are excluded. Their confirmation and recovery capabilities, plus the cleanup decision, stay in a human-owned CLI flow.
One-time secret creation and redemption stay in a human-controlled encryption client.
Public capability resolution and downloads, plus the readiness probe, have no authenticated agent workflow.

Reference and troubleshooting

Syntax and behavior

Reusable syntax

interactive and unattended MCP syntax

blobyard mcp serve --stdio
BLOBYARD_TOKEN=<scoped-token> blobyard mcp serve --stdio

Concrete example

approved local MCP host

blobyard login --name "Agent host"
blobyard mcp serve --stdio

Values used

serve: Starts the local MCP adapter embedded in the native CLI.
--stdio: Requires newline-delimited MCP traffic over standard input and output.
BLOBYARD_TOKEN: Optional scoped token for an unattended host. Store it in the host secret manager, not a prompt or config committed to source.
Agent host: Neutral CLI-session label visible in Settings.

Expected result

The MCP client discovers Blob Yard tools, resources, and prompts under the authority of the approved session or token scopes.

If it fails

Run blobyard whoami before MCP startup to verify the approved CLI session.
Create a new scoped token if an unattended token expired or was revoked. Never reuse the raw value from logs.

Security and lifecycle

MCP standard output contains protocol messages only. Tokens, refresh credentials, storage keys, and signed transfer URLs must not enter agent prompts or transcripts.