Skip to main content

Enabling the MCP Server

The MCP server is off until you enable it. Flipping it on takes about 30 seconds.

Turn it on​

  1. Open Preferences (Tools → Preferences, or Ctrl + ,).
  2. Find the MCP Server section.
  3. Set the port (workspace-specific; default 3000).
  4. (Optional) Tick Start MCP server when this workspace loads to auto-start the server each time you open this workspace.
  5. (Optional) Tick Allow AI agents to modify data in this workspace if you want write tools enabled here.
  6. Click Apply.

The server starts immediately. You'll see its status in the status bar at the bottom of the main window:

IndicatorMeaning
MCP: Running (3000)Listening on the port shown.
MCP: StoppedDisabled, or stopped manually.
MCP: ErrorFailed to start; hover for the reason.

Quick toggle from the status bar​

The MCP icon in the status bar is also a button. Click it to start the server if it is stopped, or stop it if it is running. Hover over the icon for its current state and port. This is the fastest way to flip the server on and off during a working session without opening preferences.

Port​

The default is 3000. Port is a workspace-specific setting; each workspace keeps its own value. This means two DataStar instances can run side-by-side against different workspaces without colliding on a shared port. Change it in the MCP preferences pane if you need to:

  • Another application is already using port 3000.
  • You want two workspaces open simultaneously, each with its own MCP server.

The server binds to 127.0.0.1. It never listens on an external interface, regardless of the port you choose.

Allow write access​

Read tools (everything marked ReadOnly in the catalog) work as soon as the server is on.

Write tools require an extra opt-in per workspace. Tick Allow AI agents to modify data in this workspace in the MCP preferences pane. Because the setting is workspace-scoped, you can trust writes in a development workspace while leaving them disabled in a production-facing one. While off, the agent still sees the full tool schema but receives an error the moment it tries to mutate anything.

What 'write' covers
  • Creating or applying drafts.
  • Adding components to the deployment basket.
  • Extracting scripts to the workspace.
  • Deleting components.
  • Committing tasks, transitioning status, posting comments.
  • Running execute_script or execute_sql with dryRun=false (i.e. committing SQL).

It does not cover reading the database, reading workspace files, or running execute_query.

Regenerate the API key​

The MCP server protects itself with an API key. Every request from an AI client must present it.

  • On first start, an API key is generated for you. Copy it from the MCP preferences pane.
  • Click Regenerate to invalidate the old key and create a new one. Any AI client still using the old key will get a 401 on the next call; reconfigure it with the new key.
  • Rotate the key if you've pasted it somewhere it shouldn't have gone.

Verify it's working​

The status bar at the bottom of the main window is the primary indicator. MCP: Running (3000) means the server is listening and ready for connections.

For a quick end-to-end check from a terminal, send an MCP initialize request:

curl -X POST http://127.0.0.1:3000/mcp \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'

A healthy server responds with a JSON-RPC result describing its capabilities. If you get:

  • Connection refused. The server isn't running. Check the status bar.
  • 401 Unauthorized. Your API key is wrong or missing.
  • 403 Forbidden. The request isn't coming from the local machine. Only loopback traffic is accepted.

Stopping the server​

  • Click the MCP icon in the status bar; toggles the server off immediately.
  • Untick Enable MCP server in preferences and save; stops immediately.
  • Quitting DataStar stops the server too.

The server does not keep running in the background after DataStar closes, even if Start on launch is on.

Next​

Last updated on