Skip to main content

Using MCP from an AI Client

DataStar's MCP server speaks standard Model Context Protocol, so any MCP-capable client works. This page covers the two most common (Claude Desktop and Kiro), plus the generic recipe for anything else.

Before you start, make sure the server is running and you have your API key and port to hand.

Claude Desktop​

Claude Desktop reads its MCP configuration from a JSON file at %APPDATA%\Claude\claude_desktop_config.json. Add a mcpServers entry:

{
  "mcpServers": {
    "datastar": {
      "url": "http://127.0.0.1:3000/mcp",
      "headers": {
        "X-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Restart Claude Desktop. The DataStar tools will appear in the tool picker. Test it by asking something simple:

"What workspace is DataStar currently connected to?"

The agent should call get_workspace_info and answer with your workspace name, project directory, and categories.

Kiro​

Kiro supports MCP via its settings UI:

  1. Open Kiro settings.
  2. Find MCP servers.
  3. Add a server:
    • Name: datastar
    • URL: http://127.0.0.1:3000/mcp
    • Header: X-API-Key: YOUR_API_KEY
  4. Save and reload.

Verify by asking Kiro to list your workspace components:

"List the tables in my current workspace."

Any other MCP client​

The generic contract:

  • Transport: HTTP
  • URL: http://127.0.0.1:<port>/mcp (default port 3000)
  • Authentication: X-API-Key: <api-key> header on every request. Clients that only speak OAuth-style headers may send Authorization: Bearer <api-key> instead; the server accepts either.
  • Protocol: standard MCP. Tool discovery via tools/list, invocation via tools/call.

If the client has a concept of "HTTP MCP servers", those four fields are all it needs.

A good first conversation​

Once the client is connected, a productive opening sequence for the agent is:

  1. get_workspace_info: confirm which workspace is open and which categories it exposes.
  2. get_database_context: find the effective schema and user.
  3. metadata_table(action='list'): see what's available for dictionary queries.

From there, most schema questions can be answered with get_table_details or metadata_table(action='query'), and most change questions with list_components and get_component_content.

Common tasks​

"Explain this table"​

Me: "What's in APP.ACCOUNTS?"

Agent: calls get_table_details(schema='APP', tableName='ACCOUNTS'), formats the columns, primary key, and foreign keys as a summary.

"Show me the UDF columns"​

Me: "What user-defined columns exist on ACCOUNTS?"

Agent: calls metadata_table(action='query', tableName='UDF_CONFIG', filters=[{column:'TABLE_NAME', operator:'=', value:'ACCOUNTS'}, {column:'COLUMN_NAME', operator:'LIKE', value:'UDF_%'}]), lists the matches.

"What would break if I change X?"​

Me: "What components depend on the ACCOUNTS view?"

Agent: calls get_dependencies(category='Views', name='ACCOUNTS', direction='reverse', scanAllCategories=true) and lists the matches. If Truncated=true it can ask for a higher maxScan.

"Stage this change for release"​

Requires write access enabled.

Me: "Add Tables/ACCOUNTS.sql to the deployment basket."

Agent: calls update_basket(action='add', category='Tables', name='ACCOUNTS'). The component appears in your basket immediately.

Troubleshooting​

Claude or Kiro doesn't see DataStar tools. Most often a stale config. Fully quit the client (not just close the window) and relaunch.

401 Unauthorized. API key mismatch. Copy it fresh from the DataStar MCP preferences and paste.

Connection refused. Server isn't running. Check the status bar in DataStar.

"Write operations are disabled". The agent tried a mutating tool. Tick Allow write access in DataStar's MCP preferences.

"Table X is not in the configured metadata tables". Add it in Workspace Settings → MCP. See Configuring Metadata Tables.

The agent uses the wrong schema. Tell it to call get_database_context first. If the schema it returns is wrong for your target table, pass the correct one explicitly on tools that accept a schema parameter.

See also​

Last updated on