The HostTracker MCP server connects AI assistants to HostTracker's availability monitoring service through the Model Context Protocol (MCP), letting users operate their own monitoring accounts directly within a conversation.\n\n[Purpose]\nThis repository is the public face of the hosted server, containing connection metadata (server.json), setup guides for each client (CLIENT.md), and the security policy (SECURITY.md). Since 2.0.0, the server's own source code is also included in the src/ directory, so users can inspect the code actually running behind the endpoint or run a copy themselves.\n\n[Main capabilities]\n• Run real-time checks from more than 300 locations worldwide\n• See which monitors are down\n• Create or pause monitors\n• Schedule maintenance windows\n• View incidents\n• Manage alert recipients\n• Configure webhooks\n• Publish status page updates\n\nThe server exposes the HostTracker v2 REST API as MCP tools. Every list tool accepts limit (maximum 50) and cursor parameters and returns the next cursor; all timestamps are Unix seconds in both directions; ids are opaque strings.\n\n[Usage]\nYou can connect via two authentication methods:\n1. OAuth (recommended; works with Claude.ai, Claude Desktop, Claude Code, ChatGPT, and any client that supports the OAuth connector dialog): add the endpoint https://mcp.host-tracker.com/mcp as a connector, sign in and approve authorization (the default permissions are run checks + read monitors), with no token required.\n2. Bearer Token: pass Authorization: Bearer YOUR_HOSTTRACKER_API_TOKEN in the request header.\n\nClient configuration:\n• Claude.ai / Claude Desktop: Settings -> Connectors -> Add custom connector -> paste the URL -> Connect.\n• Cursor: edit ~/.cursor/mcp.json or .cursor/mcp.json.\n• VS Code (GitHub Copilot agent mode): configure in the workspace's .vscode/mcp.json.\n• Windsurf: edit ~/.codeium/windsurf/mcp_config.json.\n• ChatGPT (Developer mode -> Connectors): add the URL, using the "Link account" step.\n\nRun it yourself (Docker): the repository can be built from source, and after running, the copy is at http://localhost:8080/mcp response, using the same Authorization: Bearer header. The service is a stateless bridge, stores nothing, and still communicates with the public HostTracker API v2 using the user token. When not using Docker, dotnet run --project src achieves the same effect on any machine with the .NET 10 SDK installed. The same binary also supports stdio, suitable for clients that start the server as a subprocess; add --stdio and pass the token via the HT_TOKEN environment variable; in that mode logs are output to stderr.\n\n[Behavior characteristics]\n• Batch operations validate first: batch tools return a validation report, and writing requires an explicit second call with submit=true; batch deletion also requires confirmed=true and the count from a passing validation report.\n• Batch operations and reports are asynchronous: they return a job id, which you poll with wait_for_job.\n• Deletion is irreversible and always requires two calls: the first call deletes nothing and only returns the resource for confirmation; only a repeated call with confirmed=true performs the deletion, and the API returns a deletion receipt.\n\n[Authentication and permission scopes]\nOAuth connection: the user logs in once and approves the permission set on the consent page, and the server issues a short-lived access token (1 hour) and a rotating refresh token (90 days). If the client does not request any scopes, it gets check + monitor:read. Account family permissions can never be granted to connected apps. All connections are listed under "Integrations -> API -> Connected apps" and can be revoked with one click. When a scope is missing, tools return missing_scope and explain the required permission.\nBearer Token: created under "Integrations -> API", with selectable scopes, expiration time, and an optional IP allowlist.\nScopes are divided by family; the :read and :write leaf permissions do not imply each other; a bare family name satisfies all leaves under it. It is recommended to grant the minimum set of permissions covering what is needed for the work. account:write never needs to be granted: regardless of what the token allows, the server rejects all writes under /account.\n\n[Limits and quotas]\n• Endpoints enforce rate limiting on /mcp per client IP; throttled responses carry Retry-After, which the server passes through as-is and does not sleep or retry on your behalf.\n• API plan quotas are enforced against the user's own token, the same as direct REST calls. get_account_usage and get_account_quota can report usage. • Application failures (no token, wrong scope, exhausted quota, invalid input) are returned as ordinary tool results with actionable messages, not protocol errors. • The server is stateless and stores nothing: every call is forwarded to the API with the user's own token, and ownership, quotas, and rate limits are enforced on the API side. • Security restrictions: regardless of the token, the server rejects any writes under /account, as well as any operation involving payments, plans, passwords, login, or API token minting. Content controlled by the inspected target is wrapped in an isolated block with a length cap before reaching the model, preventing malicious targets from injecting instructions into the assistant.
[Use cases] Operations personnel and teams that need to operate website availability monitoring conversationally, quickly understand service status, manage monitoring and alerts, and handle incidents and status pages.
[Limitations] • OAuth access tokens are valid for 1 hour, and refresh tokens for 90 days. • The maximum limit for list tools is 50. • Bulk operations and reports are asynchronous and require polling the job id. • Delete operations are irreversible and require two calls to confirm. • The account family of permissions cannot be granted to connected apps, and /account write operations are always rejected. • The contents of this repository (documentation and metadata) are released under the MIT License; the hosted MCP server and the HostTracker service itself are proprietary software.
[Other information] Official clients include JavaScript, Python, Go, .NET, CLI, an OpenAPI description, and a GitHub Action. API v2 reference and guides are available in the official HostTracker documentation. Support email: ht2support@host-tracker.com. For the security policy, see SECURITY.md.
