Skip to content

mcp-server.md

Latest commit

 

History

History
159 lines (125 loc) · 6.75 KB

mcp-server.md

File metadata and controls

159 lines (125 loc) · 6.75 KB

MCP server

Hoptimator ships an MCP server so AI agents, IDEs, and chat clients can drive it over the Model Context Protocol. The server is a thin wrapper around the JDBC driver — it exposes a fixed set of tools that map onto the catalog, the planner, and the deployer.

Launch

After make build install, the start script lives at the repo root:

./start-mcp-server

Under the hood it runs:

hoptimator-mcp-server-app \
  com.linkedin.hoptimator.mcp.server.HoptimatorMcpServer \
  "jdbc:hoptimator://fun=mysql"

The last argument is the JDBC URL the server connects to. To target a different namespace or kubeconfig, edit the script or invoke hoptimator-mcp-server-app directly with your URL of choice. See JDBC driver for the full URL format.

The server speaks MCP over stdio. It does not open a network port.

Configuring an MCP client

Most MCP clients accept a mcpServers config block. Pointing one at Hoptimator looks like:

{
  "mcpServers": {
    "hoptimator": {
      "command": "/absolute/path/to/Hoptimator/start-mcp-server",
      "type": "stdio"
    }
  }
}

Some clients require an explicit JAVA_HOME. If you see java: command not found or version mismatches, set it in env:

{
  "mcpServers": {
    "hoptimator": {
      "command": "/absolute/path/to/Hoptimator/start-mcp-server",
      "type": "stdio",
      "env": {
        "JAVA_HOME": "/path/to/jdk-17"
      }
    }
  }
}

Tools exposed

The server registers a fixed set of tools. They split into three groups: discovery (read-only catalog and pipeline state), planning (dry-run a mutation), and execution (actually mutate state).

Discovery (read-only)

Tool Arguments Returns
fetch_schemas catalog? All (catalog, schema) pairs visible to the connection.
fetch_tables catalog?, schema? Tables, optionally filtered by catalog/schema.
describe_table table (required), catalog?, schema? Columns, primary key, foreign keys.
fetch_pipelines (none) Every pipeline currently deployed in the namespace.
fetch_pipeline_status pipeline (required) Per-element ready/failed/message detail for a pipeline.
describe_pipeline pipeline (required) The view SQL behind a deployed pipeline.

Planning (read-only, but expensive)

Tool Arguments Returns
plan sql (required) The list of YAML specs the SQL would deploy. The MCP equivalent of the CLI's !specify.

plan accepts CREATE [OR REPLACE] MATERIALIZED VIEW ... and DROP ... statements. It does not mutate state; use it to preview a change before calling modify.

Execution

Tool Arguments Returns
query sql (required) Rows from a SELECT. Currently a proof-of-concept — see below.
modify sql (required) Result of a CREATE MATERIALIZED VIEW / DROP. Actually deploys.

modify only accepts CREATE [OR REPLACE] MATERIALIZED VIEW and DROP statements. Other DDL is rejected.

About query

query is a proof-of-concept. It is hardcoded to accept reads only from the ADS, PROFILE, METADATA, and K8S schemas, and will refuse anything else. The reason isn't safety — it's that those four are the only schemas where Hoptimator can answer the query itself:

  • ADS, PROFILE, METADATA are in-memory demodb databases used by the quickstart. Their data exists in the JVM and Calcite can compute results directly.
  • K8S is the system schema that exposes Hoptimator's own state.

Querying any other schema (Kafka, Venice, MySQL, Flink-managed tables, etc.) requires an engine — typically a Flink session job — to actually run the SQL. Hoptimator does not yet ship engine definitions for most adapters, so those queries can't be executed end-to-end. (An earlier proof-of-concept explored notebook-style execution via Zeppelin; it's incomplete.)

For now, treat query as a way to introspect the demo schemas and Hoptimator's own state. To inspect the shape of a real source, use describe_table. To deliver data continuously to a destination you can query, use modify to create a materialized view.

Recommended agent workflow

The tool boundary is designed so an agent can be safely autonomous on discovery but gated on mutation. A reasonable pattern:

  1. Browse. fetch_schemas → fetch_tables → describe_table to find the right inputs and the right output sink.
  2. Draft. Compose a CREATE MATERIALIZED VIEW statement.
  3. Plan. Call plan with the draft. Show the resulting YAML to the user (or have the agent reason over it) before doing anything else. The plan contains every resource that would land in the cluster.
  4. Apply. Only after the plan is reviewed, call modify with the same statement.
  5. Verify. Poll fetch_pipeline_status until each element is ready, or surface the failing element's message.

If your client supports it, configure modify to require explicit confirmation per call. Hoptimator does not enforce this — the gate has to come from the host agent.

Limitations to know

  • The server does not implement MCP's resources or prompts surfaces; only tools.
  • The connection is established at server start; namespace and credentials cannot be changed mid-session. Restart with a different JDBC URL to switch contexts.
  • modify does not yet expose the full Hoptimator DDL surface — only CREATE [OR REPLACE] MATERIALIZED VIEW and DROP are accepted today. Triggers, plain views, tables, and the inspection-only DDL (reference) need to be driven through the JDBC driver or the SQL CLI for now.
  • query is proof-of-concept and is restricted to the in-memory demo schemas plus the K8S system schema (see About query). Production-style querying will require an engine to be configured and is not yet supported.