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, which categories it exposes, and which dictionary tables are configured.
  2. list_saved_connections: see which databases it can run against, and pass one as connection.
  3. execute_sql (read mode): resolve the effective schema and user, and inspect physical schema by SELECTing from INFORMATION_SCHEMA / sys.* / the Oracle data dictionary.

From there, most schema questions are answered with read-only execute_sql queries — including against the configured dictionary tables — and most change questions with find_components plus reading the component's .sql file directly.

Common tasks​

"Explain this table"​

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

Agent: runs a read-only execute_sql query against the data dictionary (e.g. INFORMATION_SCHEMA.COLUMNS plus the key/constraint views, or the Oracle ALL_TAB_COLUMNS / ALL_CONSTRAINTS equivalents), then 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: runs execute_sql in read mode against the configured UDF_CONFIG dictionary table — SELECT column_name FROM UDF_CONFIG WHERE table_name = 'ACCOUNTS' AND column_name LIKE 'UDF_%' — and 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 manage_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.

The agent doesn't know about a dictionary table. It's told about the tables you configure in Workspace Settings → MCP (surfaced via get_workspace_info). Add it there, or name it directly in your prompt. See Configuring Metadata Tables.

The agent uses the wrong schema. Tell it to resolve the effective schema first with a read-only execute_sql query (e.g. SELECT SCHEMA_NAME() on SQL Server, or SELECT SYS_CONTEXT('USERENV','CURRENT_SCHEMA') FROM DUAL on Oracle), then qualify names from that.

See also​

Last updated on