Agent contract

Docs for the agent reading this page.

Connect the MCP server, present the token as a bearer header, then choose the narrowest tool that matches the artifact you need to host.

Endpoint

https://founders.host/api/mcp

Header

Authorization: Bearer YOUR_TOKEN

server

founders-host

transport

streamable-http

inline limit

3 MB decoded

large flow

request_upload -> host_complete

Install

Give the client this server definition.

Use the snippet that matches the agent runtime. After saving, reload MCP tools before calling host_file.

Claude Code

Run in your terminal

command

claude mcp add --transport http founders-host https://founders.host/api/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

Codex CLI

Run in your terminal

command

export FOUNDERS_HOST_TOKEN="YOUR_TOKEN"
codex mcp add founders-host --url https://founders.host/api/mcp \
  --bearer-token-env-var FOUNDERS_HOST_TOKEN

Hermes Agent

Hermes MCP config profile

yaml

mcp_servers:
  founders-host:
    url: "https://founders.host/api/mcp"
    headers:
      Authorization: "Bearer YOUR_TOKEN"
    enabled: true
    timeout: 120
    connect_timeout: 60
    tools:
      resources: false
      prompts: false

OpenClaw

~/.openclaw/openclaw.json

json5

{
  mcp: {
    servers: {
      "founders-host": {
        url: "https://founders.host/api/mcp",
        transport: "streamable-http",
        headers: {
          Authorization: "Bearer YOUR_TOKEN",
        },
      },
    },
  },
}

Tools

Tool inventory and routing rules.

Pick the most specific write verb. Use request_upload only as a preflight, and host_complete only as the finalizer.

Tool	Purpose	Input shape	Use when
host_file	Generic write path for generated files or URL re-hosting.	filename plus content or url	Use when no specialized verb fits.
screenshot_to_url	Image-specific write path with preview-friendly metadata.	base64 image, optional filename	Use for screenshots and generated images under the inline limit.
host_landing	Publish HTML to a live landing page path.	slug and html	Use for generated one-page sites and demos.
host_doc	Save markdown as a clean reader page.	markdown, optional title and filename	Use for reports, specs, notes, and handoffs.
request_upload	Preflight large files before sending bytes.	filename, size, contentSha256, optional localPath	Use before any local file that may exceed 3 MB.
host_complete	Finalize a request_upload session after bytes are PUT.	key, uploadBand, size, contentSha256, optional multipart data	Use only after request_upload returns a session.
get_file_url	Resolve a stored artifact key to a URL.	filename, optional raw	Use when the file already exists.
list_artifacts	Browse artifacts owned by this token.	query, contentType, visibility, limit, offset	Use before asking the user to remember a filename.

Large file protocol

Never base64 a huge local file into MCP.

Use the control-plane flow so bytes move directly to storage.

Claim a token View pricing

Preflight

Call request_upload with filename, decoded size, contentSha256, contentType, and localPath when the client can run shell commands.

PUT bytes

If a session is returned, run the provided clientUpload.commands or PUT each part to the presigned URL set.

Finalize

Call host_complete with the key, uploadBand, quotaReservationId, size, hash, and multipart ETags when needed.

Operating rules

Constraints the agent should keep in working memory.

Authorization is always the bearer token from /claim or /account.

Inline content is for files under 3 MB decoded. Larger files use request_upload.

Public artifacts get durable Founders.host share URLs. Private artifacts resolve through signed URLs.

Every write stores provenance with content hash and agent metadata when provided.

Tokens are scoped. One token cannot read or delete another token's artifacts.

Remote MCP cannot read your local filesystem. Use localPath only when the client can run returned shell commands.

Prompts

Useful instructions to give the agent.

Host this screenshot with screenshot_to_url and return the Founders.host URL.

Save this markdown as docs/status-brief.md with host_doc.

This local video may be large. Run request_upload first, then host_complete.