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:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Add a mcpServers entry:

{
  "mcpServers": {
    "datastar": {
      "url": "http://127.0.0.1:3000",
      "headers": {
        "Authorization": "Bearer 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
    • Authorization header: Bearer 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> (default 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.
  2. get_database_context — find the effective schema and user.
  3. list_metadata_tables — see what's available for dictionary queries.
  4. list_categories — see what kinds of components exist.

From there, most schema questions can be answered with get_table_details or query_metadata_table, 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 query_metadata_table('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_reverse_dependencies(category='Views', name='ACCOUNTS', 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 add_to_basket('Tables', '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