IDE Integration

Any IDE or coding agent that supports MCP can connect directly to the AI Optimizer and use the same RAG tools, prompts, and resources that the built-in client uses. For tools that do not support MCP, a limited OpenAI-style compatibility path is available.

Supported IDEs

Prerequisites

1. Install and configure the AI Optimizer.
2. Configure at least one usable language model.
3. Configure a database if you want Vector Search or NL2SQL features.
4. If you want Vector Search, embed your documents first — see Split & Embed.
5. Install Oracle SQLcl if you want NL2SQL tools.
6. Start the API Server — see API Server.

If AIO_API_KEY was not set before startup, retrieve the generated key from the API Server page or via Configuration.

Verify the server before connecting an IDE:

curl http://localhost:8000/v1/liveness
curl -H "X-API-Key: $AIO_API_KEY" http://localhost:8000/mcp/healthz

MCP Integration

This is the preferred path for any IDE or agent that supports MCP.

Get the Client Configuration

The server generates a ready-to-use client configuration:

curl -H "X-API-Key: $AIO_API_KEY" \
  http://localhost:8000/mcp/client-config | jq .

Example output:

{
  "mcpServers": {
    "oracle-ai-optimizer": {
      "type": "streamableHttp",
      "transport": "streamable-http",
      "url": "http://localhost:8000/mcp/",
      "headers": {
        "X-API-Key": "..."
      }
    }
  }
}

Paste the oracle-ai-optimizer entry into your IDE’s MCP server configuration. Refer to your tool’s MCP documentation for the exact location — most tools expose this under a dedicated MCP or AI server settings panel.

After adding the server, verify the connection:

curl -H "X-API-Key: $AIO_API_KEY" http://localhost:8000/mcp/tools
curl -H "X-API-Key: $AIO_API_KEY" http://localhost:8000/mcp/prompts

Available MCP Tools

SQLcl tools (sqlcl_*) are registered automatically when SQLcl is available and a database is configured. They provide read-only database access: schema inspection, SQL execution, and session metadata.

OpenAI-Style Compatibility

Some tools — primarily terminal assistants like aider — do not support MCP and need an OpenAI-style endpoint.

The AI Optimizer exposes /v1/chat/completions and /v1/chat/streams, but these are Optimizer-specific endpoints, not drop-in OpenAI wire-compatible routes:

• Authentication uses X-API-Key, not Authorization: Bearer.
• Model selection comes from the client’s saved settings, not the model field in the request body.
• Responses return a custom {role, content, route, vs_metadata, token_usage} object, not the OpenAI choices envelope.
• Streaming uses custom SSE event types, not OpenAI delta events.

For tools that cannot speak MCP or accommodate a custom auth header, the recommended path is the Spring AI sample or a thin reverse-proxy adapter.

aider

aider does not support MCP and sends Authorization: Bearer, which the Optimizer does not accept directly. Use a reverse proxy to rewrite the auth header, or point aider at the Spring AI sample endpoint instead.

Tool Configuration

Each client maintains independent settings, including which tools are enabled. Set tools_enabled per client:

curl -X PUT "http://localhost:8000/v1/settings?client=my-ide-session" \
  -H "X-API-Key: $AIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tools_enabled": ["Vector Search", "NL2SQL"]}'

Enabling Vector Search also depends on vector search settings such as which store to query and whether discovery, rephrase, and grade nodes are active. Models under 7B parameters automatically disable rephrase and grade. See VecSearch Flow and Chatbot for details.

Use the client header on chat requests to isolate conversation history and settings across IDE sessions:

curl -X POST http://localhost:8000/v1/chat/completions \
  -H "X-API-Key: $AIO_API_KEY" \
  -H "client: my-ide-session" \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "Hello"}]}'

Tool Routing

When both tools are enabled the runtime routes automatically based on question semantics. See VecSearch Flow and NL2SQL Agent for how each path works.

Troubleshooting

403 Forbidden — The X-API-Key header is missing or incorrect. Retrieve the key from the API Server page.

MCP tools not visible — Check /mcp/healthz and confirm tools are registered:

curl -H "X-API-Key: $AIO_API_KEY" http://localhost:8000/mcp/healthz

NL2SQL tools missing — Verify SQLcl is in PATH and a database is configured. Check server logs for the SQLcl proxy registration message.

Model not found — Confirm the model is enabled in Configuration → Models and list configured models to verify:

curl -H "X-API-Key: $AIO_API_KEY" http://localhost:8000/v1/models

Related

• Custom MCP Tools
• VecSearch Flow
• NL2SQL Agent
• Split & Embed
• API Server
• API Examples
• Spring AI
• Troubleshooting