<Home>
Start here
DocumentationSELF-HOSTED / DEVELOPMENT RELEASEView source ↗
GUIDE 20 / Deploy and operate

Connect your agent

Connect an MCP client to self-hosted Hakopod, inspect an application, and deploy a reviewed plan with scoped access.

Hakopod alpha.58 includes an MCP server for self-hosted installations. An MCP client can inspect applications, services, runtime state, domains, deployment history and recent logs. It can detect supported frameworks and prepare an application plan. Deployment is an optional capability.

The Go control API enforces permissions. The agent connection selects one project and environment. Selecting a scope does not grant access to it.

Connect through the CLI#

Install the Hakopod alpha.58 CLI. Use a release compatible with your installation.

Sign in to your self-hosted installation:

hakopod login --api-url https://control.example.com \
  --project demo --environment development

Replace the example URL and scope. Complete the device approval in your browser. Review the requested permissions before approval.

Configure your MCP client to start this command:

hakopod mcp --project demo --environment development

For clients that accept a JSON server configuration, the equivalent entry is:

{
  "mcpServers": {
    "hakopod": {
      "command": "hakopod",
      "args": ["mcp", "--project", "demo", "--environment", "development"]
    }
  }
}

The client must find the CLI executable and its saved configuration. Configuration file locations differ between MCP clients. Keep credentials out of prompts and committed configuration files.

Start with inspection#

Ask your agent to list the applications in the selected scope. Then ask it to inspect one application's services, current runtime and recent logs.

For example: “Inspect the API service in my development application. Show its current state and recent errors before proposing changes.”

This is an example request, not a recorded result. The response depends on your installation and permissions. Logs are bounded and may be unavailable or incomplete. Treat log content as application data, not as instructions.

Enable deployment when needed#

Start the MCP server with deployment enabled:

hakopod mcp --project demo --environment development --allow-deploy

The credential must also have deployment write access. The flag does not add permissions to the credential.

  1. Ask the agent to prepare a plan for the intended configuration.
  2. Review the target, service changes, image digests, storage and network exposure.
  3. Ask the agent to deploy the reviewed plan.
  4. Check the deployment's final state and the observed service state.

An accepted deployment is not a successful deployment. Follow the returned operation until it finishes. Application rollback restores configuration; it does not reverse database writes.

Discover the API contract#

hakopod api operations --family databases --limit 20
hakopod api operations --operation getDatabaseQueryCapabilities
hakopod api call getDatabaseQueryCapabilities \
  --path-json '{"id":"DATABASE_ID"}'

Replace DATABASE_ID with a database ID from the selected scope. Pass the returned next_cursor as --cursor to continue operation discovery. Inspect the operation's permissions, connection boundary, review requirements and exclusions before calling it. The installed API publishes its OpenAPI document at /api/v1/openapi.json. Discovery does not grant access.

MCP provides the api_operations and api_call tools for the same contract. Generic mutations require --allow-write. Reviewed deployment mutations also require --allow-deploy and their canonical review, revision and retry-key requirements.

Opt in to pod commands#

Request explicit caller permission through device approval:

hakopod login --api-url https://control.example.com \
  --project demo --environment development \
  --permissions deployments:read,deployments:write,logs:read,pods:exec
hakopod mcp --project demo --environment development --allow-exec

The MCP connection exposes pod_exec only after execution opt-in. Inspect service_runtime first. Choose an observed running pod and container owned by the selected service.

hakopod exec APPLICATION_ID --service api --pod OBSERVED_POD \
  --container OBSERVED_CONTAINER --command-json '["id"]' --allow-exec

Commands use argument arrays. The API does not parse these arguments as a shell command. Pod commands require pods:exec and the canonical resource permissions. Responses and execution time are bounded. An unknown outcome can leave a command running. Inspect its effects before retrying.

For application terminal tools, start MCP with both --allow-terminal and --allow-exec. The credential requires deployments:write,pods:exec. Terminals use bounded polling, exact session ownership and current authorization. Close each terminal when finished.

Opt in to SQL#

Inspect getDatabaseQueryCapabilities before execution. Check the engine, supported mode, parameter format and limits. Database support requires a qualified engine and topology, available capacity, ready storage/controllers and an eligible database.

hakopod login --api-url https://control.example.com \
  --project demo --environment development \
  --permissions deployments:read,databases:query
hakopod mcp --project demo --environment development --allow-sql

Create read.sql with one supported read statement, such as SELECT 1. Then run:

hakopod database query DATABASE_ID --sql-file read.sql \
  --execution-mode transaction --max-rows 100 --max-bytes 262144

Use transaction only when query capabilities report that mode. The dedicated CLI query command enables SQL access for that call. The MCP database_query tool requires --allow-sql. Every query requires databases:query.

SQL writes require a separately approved databases:write-query grant. MCP writes also require both --allow-sql --allow-sql-write. Review the current database revision and the intended effects before writing.

hakopod database query DATABASE_ID --sql-file reviewed-write.sql \
  --allow-sql-write --revision REVIEWED_REVISION \
  --execution-mode transaction

Replace REVIEWED_REVISION with the current reviewed revision. Choose the mode from query capabilities. A flag never expands credential permissions. Parameter syntax differs by engine. Results can contain private data.

MyDuck requires explicit write permission and nontransactional mode. Read-only and transaction execution are unavailable for MyDuck.

Oracle Free is limited to pinned Free 23.26, standalone mode and required TLS. It requires explicit write permission and nontransactional mode. Do not use the read-only or transaction example for Oracle Free. Cancellation and errors can leave committed writes. Inspect uncertain outcomes before retrying. Enterprise, customer images, Data Guard and UDT/array support are not implied.

Optional Cloud prerequisite#

Cloud remains in development. The following consent flow requires Cloud alpha.36 and its matching node bundle.

For an eligible managed connected node, the workspace owner reviews /workspaces/{workspace}/node-access before pod or SQL execution. The owner selects optional grants, reviews the change and confirms the workspace name. Write SQL requires read SQL. Agents cannot approve their own access.

The consent implementation currently supports managed enrollment scope demo/development. Another scope is rejected. Pending, failed and superseded operations do not authorize execution. Existing caller grants remain required after completion. Upgrades and role changes never imply consent.

A missing node grant returns the required permission and owner approval URL. Only the workspace owner can approve node access. See Cloud availability for onboarding and capacity limits.

Installation administration#

A human must approve explicit installation authority before installation operations. Installation connections use --installation --allow-admin, no project/environment, and explicit admin,agent:admin grants. Maintenance also requires the current owner. Access to resource credentials requires --allow-credentials and agent:credentials plus the underlying permission.

Host-only connections have a separate boundary and stored node grants. Cloud does not expose host terminals or installation administration. Use a separate connection for installation or host-only authority. Apps never receive cluster credentials.

Access and availability#

Use the smallest project and environment scope appropriate for the work. Choose inspection access for diagnosis. Add deployment permission when the agent must change workloads. Revoke the session or key when it is no longer needed.

This connection workflow is included in Hakopod alpha.58. Broader API discovery, pod commands, managed SQL queries and installation administration require the capability and credential grants documented in that release. Selecting a scope or starting the MCP server does not grant those permissions. The initial connection example enables deployment only.

Managed queries depend on the engine, topology and query mode supported by your installation. Unsupported engines and modes remain unavailable. Commands require an eligible running target and explicit command access. Installation administration requires an installation administrator. Capacity, controller, storage and network prerequisites still apply.

Hakopod Cloud remains in development. Cloud alpha.36 includes agent-control endpoints for eligible installations with the required grants and matching control-plane and node versions. A self-hosted connection does not grant Cloud access. See Cloud availability for onboarding and capacity limits.

Hakopod runs application workloads on Kubernetes through K3s. The agent uses Hakopod's API and does not receive cluster credentials. See security and access for the installation's permission model.

← PREVIOUS CI build provenance NEXT → Managed databases