{"slug": "connect-your-ai-agents-to-your-database-without-them-having-to-write-sql", "title": "Connect your AI agents to your database without them having to write SQL", "summary": "Claix launched a hosted controlled database retrieval layer that gives AI agents read-only access to selected tables and columns in Postgres or Supabase databases without the agents writing SQL. Claix connects through a database role the user creates and limits, exposes each agent through its own endpoint with configurable routes and a plain-language business prompt, and returns validated results or typed answers over REST, MCP and A2A. Claix states it does not copy the data or build an index over it, and records every request's question, route, query and result in traces.", "body_md": "Connect your Postgres or Supabase database and give each AI agent controlled, read-only access to the tables and columns you choose. Agents ask in plain language and get validated results or typed answers over REST, MCP and A2A.\n\nClaix is a hosted **controlled database retrieval layer for AI agents**. It sits between your agent and your relational database, so the agent never has to write SQL against your tables or hold a database connection itself.\n\n```\nYour Postgres or Supabase database   (read-only role)\n        ↓\nData Map: tables, columns and relationships\n        ↓\nRoutes: which tables and columns can be used, and how\n        ↓\nAgent: its own endpoint, business prompt and routes\n        ↓\nValidated results or typed answers\n        ↓\nYour application, workflow or AI agent\n```\n\nClaix does not copy your data or build an index over it. Agents read from your database where it lives, only from what you allow.\n\n🌐 **Website:** [claix.dev](https://claix.dev)\n\n📚 **Documentation:** [claix.dev/documentation](https://claix.dev/documentation)\n\n📄 **OpenAPI specification:** [claix.dev/openapi.yaml](https://claix.dev/openapi.yaml)\n\n🤖 **A2A Agent Card:** [claix.dev/.well-known/agent-card.json](https://claix.dev/.well-known/agent-card.json)\n\n🔌 **MCP server:** [claix.dev/mcp](https://claix.dev/mcp)\n\nAn agent that needs real data from your database has two common options, and both have problems:\n\n- **Build the data access yourself** with a framework: query tools, permission checks and logging, written, hosted and maintained for every agent.\n- **Give the model a database connection** and let it write SQL. That works in a demo and is risky in production: a model can be manipulated by instructions hidden in text it reads, it can write a query that runs fine and returns the wrong answer without any error, and nobody can easily see what it did.\n\nClaix replaces both. You connect your database with a read-only role, choose which tables and columns each agent can use, and write a short note in plain language about your business rules. There is no code to write and nothing to host. Your agent sends questions to its endpoint and gets typed answers back.\n\nThe difference from a framework is that Claix is not something you build with. It is a service you call.\n\nAn agent should reason about the task it was given, not about your schema, your SQL and your permissions. Keeping those jobs apart means the agent only sees what you allow, a manipulated prompt can't give it more access than you configured, and you can see and test every answer.\n\n| Capability | What it does | \n|---|---|\n| **Read-only access** | Connects with a database role you create and limit | \n| **Data Map** | Describes your tables, columns and relationships in plain language, drafted for you to review | \n| **Routes** | Define which tables and columns can be used, with a short guide for your rules | \n| **Agents** | Each agent has its own endpoint, business prompt and routes | \n| **Typed answers** | Ask for a string, integer, boolean, array or object and get that type back | \n| **Several questions per request** | Send a list of questions and get the answers in the same order | \n| **Traces** | Every request is recorded: the question, the route, the query and the result | \n| **Sandbox** | Test your agents with real questions before connecting them to your application | \n| **REST, MCP and A2A** | Call agents from code, MCP clients, or other agents | \n| **Managed AI or BYOK** | Use the Claix model stack, or bring your own supported provider key | \n\nCreate a dedicated role limited to the tables and columns you want agents to use. Grant only what is needed.\n\n```\nCREATE ROLE claix_agent WITH LOGIN PASSWORD 'use-a-secret-manager'\n  NOSUPERUSER NOCREATEDB NOCREATEROLE NOINHERIT NOREPLICATION NOBYPASSRLS\n  CONNECTION LIMIT 10;\n\nGRANT CONNECT ON DATABASE mydb TO claix_agent;\nGRANT USAGE ON SCHEMA public TO claix_agent;\n\n-- Grant only the columns agents may use\nGRANT SELECT (id, name, country) ON public.customers TO claix_agent;\nGRANT SELECT (id, customer_id, status, total) ON public.orders TO claix_agent;\n```\n\nImportant\n\nThe role is the real barrier. Anything the role can read, an agent can ask for. Grant as little as you can, and never use a superuser or your application's main database user.\n\nIn the Claix dashboard, open **Database connection** and add the credentials of the `claix_agent` role. Claix supports **Postgres and Supabase** today.\n\nClaix reads the structure your role can see and drafts a **Data Map**: descriptions for each table, the relationships it finds and the ones it suggests. Review it, correct it and publish it.\n\nA route lists the tables and columns that can be used for one purpose, and a short guide with your rules and vocabulary. For example, a route for order status might allow `orders.status` and `orders.total`, with a note saying that `cancelled` orders stay in the table.\n\nAn agent has:\n\n- A **name** , which becomes its endpoint:`/agent/{name}` .\n- A short **description** .\n- A **business prompt** that says what the agent does and when to use each route.\n- The **routes** it can use.\n- A **response mode** : raw results or reasoned, typed answers.\n\n```\ncurl -X POST \"https://claix.dev/agent/hr-assistant\" \\\n  -H \"x-api-key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"questions\": [\n      { \"question\": \"What is the phone number of the employee named Carlos?\", \"format\": \"string\" },\n      { \"question\": \"Has the customer Javier Perez accepted marketing consent?\", \"format\": \"boolean\" },\n      { \"question\": \"What is the job title of Marta?\", \"format\": \"string\" }\n    ]\n  }'\n[\n  {\n    \"user_ask\": [\n      { \"question\": \"What is the phone number of the employee named Carlos?\", \"format\": \"string\" },\n      { \"question\": \"Has the customer Javier Perez accepted marketing consent?\", \"format\": \"boolean\" },\n      { \"question\": \"What is the job title of Marta?\", \"format\": \"string\" }\n    ],\n    \"ia_response\": [null, true, \"Waiter\"],\n    \"log_id\": \"9ff38974-1392-4c1a-83e5-3b2f09bb43dc\"\n  }\n]\n```\n\nAnswers come back in the same order as the questions. A `null` means the answer is not in the data the agent is allowed to use. Claix doesn't invent a value.\n\n| Concept | What it is | \n|---|---|\n| **Connection** | Your database, linked with a read-only role | \n| **Data Map** | A description of your tables, columns and relationships. Published as a version, so changes are deliberate | \n| **Route** | A set of tables and columns that can be used for one purpose, plus a guide with your rules | \n| **Agent** | The identity that asks questions: its own endpoint, business prompt and routes | \n| **Response mode** | Whether the agent returns raw results or reasoned, typed answers | \n| **Trace** | A record of each request: the question, the route chosen, the query that ran and the result | \n| **Sandbox** | A place to test an agent with real questions | \n\nA route defines what can be retrieved, and an agent defines who retrieves it and with which routes. Routes can be shared between agents, so a support bot and an internal assistant can use the same database and still see different data.\n\nThe business prompt is guidance, not security. Use it to explain the agent's job, when to use each route, what your terms mean and what the agent should not answer. What an agent can actually access is defined by its routes and by your database role.\n\n```\nYou are the reservations assistant for a restaurant group.\nUse the \"Bookings\" route for questions about reservations and tables.\nUse the \"Staff\" route for questions about shifts and roles.\nDo not answer questions about payments. Say that information is not available.\n\"Confirmed\" means status C; \"pending\" means P; \"cancelled\" means X.\n```\n\nAll Claix API calls require an API key. Use one of these headers:\n\n```\nx-api-key: YOUR_API_KEY\n```\n\nor:\n\n```\nAuthorization: Bearer YOUR_API_KEY\n```\n\nThe dedicated `x-api-key` header is recommended.\n\nImportant\n\nClaix API keys are server credentials. Do not expose them in browser code, mobile apps, public repositories, screenshots, client-side workflows or logs. Store them in server-side environment variables or a secrets manager. A key gives access to everything the agents it can call are allowed to see.\n\n```\nPOST https://claix.dev/agent/{name}\n```\n\n| Field | Description | \n|---|---|\n| `questions` | A list of questions. Up to 5 per request | \n| `questions[].question` | The question in plain language | \n| `questions[].format` | The type you expect: `string` ,`integer` ,`boolean` ,`array` or`object` | \n\nEach question is answered independently. Questions are not aware of each other, so write each one so it makes sense on its own.\n\n| Field | Description | \n|---|---|\n| `user_ask` | The questions you sent | \n| `ia_response` | The answers, in the same order, typed as requested | \n| `log_id` | The identifier of the request. Use it to find the full trace in the dashboard | \n\nEvery request includes a `log_id`. Use it to:\n\n- Find the exact request in your Claix traces.\n- See which route answered and what query ran.\n- Correlate Claix with your own workflow run.\n- Provide a support reference and build an audit trail.\n\nEach agent has a response mode.\n\n| Mode | What you get | Best for | \n|---|---|---|\n| **Data** | The results of the query as they are, without a second model call | Code and other agents that process the result | \n| **Answer** | A reasoned answer in the type you ask for | Results that go straight to a person, or workflows that need a single value | \n\nIn **Answer** mode, the query results are sent to the model to write the answer. That adds a model call, which means more latency and cost. It also means your data passes through the model provider, so consider that for sensitive data. **Data** is the default.\n\nEvery agent is reachable over three interfaces.\n\nCall the agent endpoint from your backend, scripts, n8n, Make, Zapier or any tool that can send an HTTP request.\n\nClaix exposes a hosted MCP server for AI assistants, coding tools and MCP-capable clients.\n\n```\nhttps://claix.dev/mcp\n```\n\nServer metadata:\n\n```\nhttps://claix.dev/.well-known/mcp/server-card.json\n```\n\nExample client configuration:\n\n```\n{\n  \"mcpServers\": {\n    \"claix\": {\n      \"url\": \"https://claix.dev/mcp\",\n      \"headers\": {\n        \"x-api-key\": \"YOUR_API_KEY\"\n      }\n    }\n  }\n}\n```\n\nClaix is a native **Agent-to-Agent (A2A)** agent. A2A-compatible agents and orchestrators can discover Claix through its public Agent Card and delegate data questions to it.\n\n```\nhttps://claix.dev/.well-known/agent-card.json\n```\n\nA2A JSON-RPC endpoint:\n\n```\nhttps://claix.dev/a2a\n```\n\nFor complete A2A documentation, see [claix.dev/documentation/a2a](https://claix.dev/documentation/a2a).\n\n```\npip install claix\n```\n\nSee the [SDK documentation](https://claix.dev/documentation/sdks) for the methods currently available.\n\n**Claix Ingest** is a separate product for getting data into your database. It turns documents, spreadsheets, images, text, HTML, XML and audio into schema-defined, source-traceable JSON, which you can then load into your own tables. Once the data is in your database, Claix Retrieve can answer questions about it.\n\n| Input type | Endpoint | \n|---|---|\n| Excel / CSV | `POST /api/excel-json` | \n|  | `POST /api/pdf-json` | \n| Documents (Word, text, markdown, RTF) | `POST /api/doc-json` | \n| Images | `POST /api/img-json` | \n| Text / HTML / XML | `POST /api/txt-json` | \n| Audio | `POST /api/audio-json` | \n\nIngest supports source tracing, persistent document context and Knowledge Spaces. Existing integrations continue to work. See the [documentation](https://claix.dev/documentation) for the full reference.\n\n| Status | Meaning | Retry? | \n|---|---|---|\n| `200` | Request completed successfully | — | \n| `400` | Invalid request, missing fields or malformed payload | No; correct the request | \n| `401` | Missing, invalid, inactive or suspended API key | No; correct credentials | \n| `404` | The agent does not exist or belongs to a different account | No; correct the name | \n| `405` | Incorrect HTTP method | No; use the documented method | \n| `413` | Request exceeds limits | No; reduce the input | \n| `429` | Rate limit exceeded | Yes; follow `Retry-After` where available | \n| `500` | Internal Claix error | Retry carefully | \n| `502` | Temporary AI-provider or processing failure | Retry with exponential backoff | \n\nError responses use a consistent shape:\n\n```\n{\n  \"error\": \"Human-readable error message.\",\n  \"detalle\": \"Optional technical detail.\",\n  \"log_id\": \"9ff38974-1392-4c1a-83e5-3b2f09bb43dc\"\n}\n```\n\nRecommended retry policy:\n\n```\nRetry:\n429, 500, 502\n\nDo not retry without changing the request:\n400, 401, 404, 405, 413\n```\n\nYou choose which model runs your agents.\n\n| Option | Best for | Billing | \n|---|---|---|\n| **Claix Managed AI** | Teams that want a managed model with no provider setup | €0.10 per question | \n| **Bring Your Own Key (BYOK)** | Teams that want to choose their model and control provider costs | €0.02 per question, plus your provider's usage | \n\n- Pricing is per question. Each question in a request counts as one question.\n- BYOK does not mean AI inference is free. Your provider bills you for tokens and any other usage.\n- With your own key, results depend on the model you choose, so test it in the Sandbox with your own routes before going live.\n- Free questions are included to start. See the [pricing page](https://claix.dev) for current details.\n\nAdd and manage keys in **LLM Keys** in the dashboard. Keys are stored encrypted and used only to run your agents' requests.\n\n- Create a dedicated **read-only** database role for Claix, with`SELECT` on only the tables and columns agents need. Prefer views for anything sensitive.\n- Do not use a superuser or your application's main database user.\n- Keep API keys and database passwords server-side, in a secrets manager. Rotate them regularly.\n- Use separate API keys for development, staging and production when possible.\n- Treat everything in your database as untrusted input. A text field can contain instructions aimed at an agent, so do not let query results override your application's rules.\n- Don't put secrets or personal data in table comments, routes or the business prompt.\n- Do not rely on the business prompt for permissions. Permissions come from your database role and your routes.\n- Review traces regularly, and keep the `log_id` alongside important workflow decisions.\n- Add your own validation for high-impact actions, such as payments, approvals, access changes or legal decisions.\n- Rotate the database password if someone who knew it leaves your team.\n\n- **Per-agent access, not per end user.** An agent can read everything its routes allow, for every user. If each person should only see their own rows, enforce that in your database or your application.\n- **Postgres and Supabase today.** Other databases are not supported yet.\n- **A hosted service.** Claix is not self-hosted.\n- **A model writes the queries.** A query can be valid, allowed and still answer the wrong question. Clear table descriptions, explicit relationships and traces help you catch that.\n- **Read-only.** Claix reads from your database. It does not change your data. Loading data is a separate step, for example with Claix Ingest.\n- **Not an analytics tool.** Claix returns data and answers to your agent. It does not include dashboards or charts.\n\nThis repository contains examples and integration guidance for the hosted Claix API.\n\nContributions are welcome for:\n\n- Examples in Python, JavaScript, Node.js, PHP and n8n.\n- Route and business-prompt examples for common use cases.\n- A2A and MCP client integrations.\n- Documentation improvements.\n- Security and reliability guidance.\n\nPlease do not commit real API keys, database credentials, private documents or customer records.\n\nUnless otherwise stated, code examples and documentation in this repository are licensed under the [MIT License](https://github.com/claix-dev/claix-for-devs/blob/main/LICENSE).\n\nClaix is a hosted service. This repository provides API examples and integration guidance; it does not provide a self-hosted Claix deployment.\n\nFor the latest endpoint details, limits, supported databases, pricing and product terms, refer to the official [Claix documentation](https://claix.dev/documentation).", "url": "https://wpnews.pro/news/connect-your-ai-agents-to-your-database-without-them-having-to-write-sql", "canonical_source": "https://github.com/claix-dev/claix-for-devs", "published_at": "2026-10-26 13:46:58+00:00", "updated_at": "2026-10-26 14:12:19.069075+00:00", "lang": "en", "topics": ["ai-agents", "agent-protocols", "ai-tools", "ai-products", "artificial-intelligence"], "entities": ["Claix", "Postgres", "Supabase", "MCP", "A2A"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/connect-your-ai-agents-to-your-database-without-them-having-to-write-sql", "markdown": "https://wpnews.pro/news/connect-your-ai-agents-to-your-database-without-them-having-to-write-sql.md", "text": "https://wpnews.pro/news/connect-your-ai-agents-to-your-database-without-them-having-to-write-sql.txt", "jsonld": "https://wpnews.pro/news/connect-your-ai-agents-to-your-database-without-them-having-to-write-sql.jsonld"}}