Developer API, connected apps and MCP

Everything the panel can do is available programmatically. There are three ways in, all built on the same set of operations, the same permissions and the same scopes:

• REST API for your own scripts and services. Needs an API key you create.
• OAuth app for an application that acts for other users. Needs a client ID and secret you register.
• MCP for an AI assistant such as Claude, Cursor or a ChatGPT style client. Needs an API key or OAuth

Everything is managed from Account > Developer.

API keys

1. Open Account > Developer.
2. Create a key, give it a name, and tick only the scopes it needs.
3. Copy the key. It starts with bhk_ and it is shown once. If you lose it, revoke it and create another.

Keys carry no expiry unless you set one, you can hold up to 25 active keys, the page shows when each was last used, and revoking one takes effect immediately.

Use it as a bearer token:

curl https://bot-hosting.net/api/v1/deployments \
  -H "Authorization: Bearer bhk_your_key"

The exact base URL for your account is shown on the Developer page.

Treat a key like a password. It carries exactly the scopes you granted, so a key for a monitoring script should hold deployments:read and nothing else.

Scopes

Check out the Developer Page for a list.

Two rules are worth remembering:

• The value of a secret environment variable is always masked, whatever scope the credential holds.
• credits:spend is what allows a credential to create something billable. Without it, a key can read your account but never spend from it.

Connected apps

The Developer page lists every third party application you have authorised, and what you granted it. Revoking a connection takes effect immediately and invalidates its tokens.

Review this list from time to time, the same way you would review connected apps on Discord or GitHub.

Building your own OAuth app

Register an app when you want other people to sign in with their Bot-Hosting account and let your app act on their behalf.

1. Create the app on the Developer page and list your redirect URIs.
2. You receive a client ID and a client secret.
3. Send users to the authorise URL shown on the page, with the scopes you need.
4. The user sees a consent screen listing exactly those scopes, and approves or refuses.
5. Exchange the returned code for tokens, then call the API with the access token.

The flow is standard OAuth 2.0 authorization code with PKCE, and refresh tokens are supported. Discovery documents are published at /.well-known/oauth-authorization-server, so most clients configure themselves.

Your app's page lists the users currently connected to it.

MCP

MCP, the Model Context Protocol, lets an AI assistant drive your account directly. Every API operation is exposed as one tool, so an assistant can list your deployments, read logs, edit files and restart an app, within the scopes of the credential you gave it.

The full list of tools is published on the MCP page of the website.

Endpoint: https://bot-hosting.net/api/mcp Authentication: your API key as a bearer token, or OAuth for clients that only speak OAuth.

Configuration for a client that reads a JSON config:

{
  "mcpServers": {
    "bot-hosting": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://bot-hosting.net/api/mcp", "--header", "Authorization: Bearer bhk_your_key"]
    }
  }
}

Quick test:

curl https://bot-hosting.net/api/mcp \
  -H "Authorization: Bearer bhk_your_key" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"deployments_list","arguments":{}}}'

Tool names are the operation names with dots replaced by underscores, so deployments.list becomes deployments_list.

Every method needs a credential, including the initial handshake. A call without one answers 401 along with the information an OAuth client needs to discover how to authenticate.

Good practice