Model Context Protocol (MCP) server

Hostless ships a remote MCP server, so an AI agent can read the documentation and operate the platform as typed tools instead of scraping a dashboard. Point Claude, ChatGPT, or Cursor at one URL and it can search the docs, or deploy and manage apps, sites, workers, cron jobs, and databases using your own credentials and scopes.

There are two endpoints, and the difference is whether the agent needs an account: /mcp/docs is public and read-only, /mcp is authenticated and acts on your resources. The server is remote HTTP, hosted at https://mcp.hostless.app, so there is nothing to install.

Endpoint	Auth	Purpose
POST /mcp/docs	None	Read Hostless documentation (docs_search, docs_get_page, docs_list)
POST /mcp	API key, JWT, or OAuth	Call platform APIs as typed tools (apps_*, projects_*, etc.)

The MCP service is separate from the REST API. Platform tool calls are proxied to https://api.hostless.dev/v1/* using your credentials. API key scopes and project roles apply the same way as direct HTTP calls.

Use /mcp/docs when you only need documentation (onboarding agents, open-source examples, or users without a Hostless account). Use /mcp when the agent should manage apps, sites, databases, and other resources.

MCP base URL

https://mcp.hostless.app

Use the URL of your deployed MCP service if self-hosting.

Route	Method	Purpose
/health	GET	Liveness check (no auth)
/.well-known/oauth-protected-resource	GET	OAuth resource metadata for /mcp
/mcp/docs	POST	Public documentation MCP (no auth)
/mcp	POST	Platform API MCP (auth required)
/mcp, /mcp/docs	GET	Not supported (returns 405)

Health check

curl -sS "https://mcp.hostless.app/health"

{
  "ok": true,
  "service": "hostless-mcp",
  "baseUrl": "https://api.hostless.dev",
  "docsMcpPath": "/mcp/docs"
}

Public documentation MCP (no auth)

Read-only access to Hostless guides, API reference, and framework tutorials. No API key, no JWT, no Authorization header.

Docs MCP URL

https://mcp.hostless.app/mcp/docs

Tool	Purpose
search	OpenAI-compatible search; returns document ids, titles, and URLs
fetch	OpenAI-compatible fetch; loads full document text and citation metadata by id
docs_search	Search documentation by keyword; returns titles, paths, snippets, and public URLs
docs_get_page	Load a full page by path (e.g. app/deployments, developers) — omit .md / .mdx
docs_list	List every documentation page

Tips for agents

• Prefer search then fetch for ChatGPT/OpenAI clients and deep-research-style retrieval.
• docs_search, docs_get_page, and docs_list remain available for existing MCP clients.
• Paths match the public docs site (https://docs.hostless.cloud/...) without the file extension.
• For deploys, billing, or resource changes, connect to the platform API MCP instead.

Connect from Cursor (no auth)

Prefer a native HTTP MCP entry — no mcp-remote bridge and no env vars:

{
  "mcpServers": {
    "hostless-docs": {
      "url": "https://mcp.hostless.app/mcp/docs"
    }
  }
}

Alternatively, use mcp-remote:

{
  "mcpServers": {
    "hostless-docs": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.hostless.app/mcp/docs"]
    }
  }
}

Restart Cursor after saving ~/.cursor/mcp.json (or your project MCP config).

Connect from Claude Desktop (no auth)

Add a streamable HTTP MCP server (Settings → Developer → MCP):

Field	Value
URL	https://mcp.hostless.app/mcp/docs
Authorization header	Omit — not required

Local development (no auth)

Run the MCP HTTP server from the monorepo:

cd hostless-api
npm run build
npm run start:mcp:http    # default http://localhost:3333

Docs are loaded automatically from hostless-docs/docs/ when the repo is checked out side by side. Set API_BASE_URL in hostless-api/.env if startup fails (required to boot the process even when you only use /mcp/docs).

Point Cursor at the local docs endpoint:

{
  "mcpServers": {
    "hostless-docs-local": {
      "url": "http://localhost:3333/mcp/docs"
    }
  }
}

Verify locally:

curl -sS http://localhost:3333/health

Docs + platform API together

Use two MCP servers in the same config — docs without credentials, platform with your API key:

{
  "mcpServers": {
    "hostless-docs": {
      "url": "https://mcp.hostless.app/mcp/docs"
    },
    "hostless": {
      "url": "https://mcp.hostless.app/mcp",
      "headers": {
        "Authorization": "hlk_a1b2c3d4_your_secret_here"
      }
    }
  }
}

For local platform API calls, swap hostless to http://localhost:3333/mcp and use your dev API key.

Platform API MCP (auth required)

Every POST /mcp request must include an Authorization header. Use the same tokens as the REST API:

Token type	Header
API key	Authorization: hlk_<prefix>_<secret>
API key (some clients)	Authorization: Bearer hlk_<prefix>_<secret>
User JWT	Authorization: Bearer <access_token>
OAuth access token	Authorization: Bearer <oauth_access_token>

Create an API key in the dashboard (Account → Settings → API Keys) with the scopes you need (for example apps:read, projects:read). The MCP server does not accept a server-wide token — each client sends its own credential on every request.

OAuth for ChatGPT and Claude connectors

AI clients can connect to Hostless MCP using OAuth 2.0 authorization code + PKCE instead of pasting an API key. When a client has no token, POST /mcp returns 401 with a WWW-Authenticate header pointing at the protected-resource metadata URL.

Discovery

Document	URL
Authorization server (API host)	https://api.hostless.dev/.well-known/oauth-authorization-server
JWKS (API host)	https://api.hostless.dev/.well-known/jwks.json
Protected resource (MCP host)	https://mcp.hostless.app/.well-known/oauth-protected-resource

Flow (summary)

1. Client discovers metadata from the URLs above.
2. Client opens GET /v1/oauth/authorize on the API with PKCE (code_challenge / S256), resource=https://mcp.hostless.app, and a registered redirect_uri.
3. Hostless redirects to the web app consent screen (/oauth/authorize). Sign in if needed, then Allow or Deny.
4. Client exchanges the authorization code at POST /v1/oauth/token for a short-lived RS256 access token and refresh token.
5. Client calls POST https://mcp.hostless.app/mcp with Authorization: Bearer <oauth_access_token>.

Scopes (v1): OAuth connectors receive read-only scopes (for example projects:read, apps:read, logs:read). Write and delete scopes are not granted to ChatGPT/Claude connectors in this release.

Revoke access: In the dashboard go to Account → Settings → Connected AI apps and revoke the connector. Access stops on the next MCP or API request.

Claude custom connector credentials

Claude requires a Client ID and Client secret in Advanced settings. Generate your own credentials in the dashboard (Account → Settings → Connected AI apps → Generate Claude credentials). Each credential pair is tied to your account — you do not need a shared platform secret.

1. Generate credentials and copy the Client ID (hloc_…) and Client secret (shown once).
2. In Claude: add a custom connector with MCP URL https://mcp.hostless.app/mcp.
3. Open Advanced settings and paste the Client ID and Client secret.
4. Complete OAuth consent when Claude connects.

ChatGPT

ChatGPT uses the public openai-chatgpt OAuth client. Per-connector redirect URLs (https://chatgpt.com/connector/oauth/{id}) are allowed via redirect URI prefix matching — no manual env configuration per connector.

Legacy shared Claude client

The seeded claude-custom-connector client remains for backward compatibility when OAUTH_CLAUDE_CLIENT_SECRET is set in server config. New integrations should use per-user credentials from the dashboard instead.

Connect from Cursor

Native HTTP MCP (Cursor 0.4.7+):

{
  "mcpServers": {
    "hostless": {
      "url": "https://mcp.hostless.app/mcp",
      "headers": {
        "Authorization": "hlk_a1b2c3d4_your_secret_here"
      }
    }
  }
}

Or use mcp-remote:

{
  "mcpServers": {
    "hostless": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.hostless.app/mcp",
        "--header",
        "Authorization:${HOSTLESS_TOKEN}"
      ],
      "env": {
        "HOSTLESS_TOKEN": "hlk_a1b2c3d4_your_secret_here"
      }
    }
  }
}

Replace HOSTLESS_TOKEN with your API key (hlk_...) or Bearer <jwt>. On Windows, omit spaces around the colon in --header (Authorization:${HOSTLESS_TOKEN}) if Cursor mangles spaced arguments.

Connect from Claude Desktop

Add a streamable HTTP server entry (Claude Desktop → Settings → Developer → MCP). Point the URL at https://mcp.hostless.app/mcp and set the Authorization header to your hlk_... token or Bearer JWT.

Exact UI labels vary by Claude Desktop version; the required values are the MCP URL and the same Authorization header as above.

Available tools

Tools mirror common platform operations. Names follow {resource}_{action}:

Resource	Tools
Projects	projects_list, projects_get, projects_create, projects_patch, projects_delete
Apps	apps_list, apps_get, apps_create, apps_patch, apps_delete
Sites	sites_list, sites_get, sites_create, sites_patch, sites_delete
Workers	workers_list, workers_get, workers_create, workers_patch, workers_delete
Cron jobs	cron_jobs_list, cron_jobs_get, cron_jobs_create, cron_jobs_patch, cron_jobs_delete
Databases	databases_list, databases_get, databases_create, databases_patch, databases_delete

Tips for agents

• Call projects_list first, then pass projectId when listing or creating apps, sites, workers, cron jobs, or databases.
• Apps, sites, workers, and cron jobs are identified by name, not MongoDB id.
• Project create/update/delete requires a user JWT; API keys can only read projects (projects:read).
• Use public documentation MCP (/mcp/docs) to look up guides without an API key.

MCP errors

Status	Meaning
401 Unauthorized	POST /mcp only — missing or invalid Authorization header (POST /mcp/docs never returns 401)
405 Method Not Allowed	GET /mcp or GET /mcp/docs — use POST for MCP requests
Tool isError: true	Platform API error (missing scope, not found, validation, etc.) — body includes the API error
Docs tool isError: true	Page not found or invalid argument (e.g. empty query or path)