> ## Documentation Index
> Fetch the complete documentation index at: https://docs.costgraph.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Graph AI

> Run Graph AI in your self-hosted CostGraph with the model provider you choose

Graph AI is the assistant in the CostGraph dashboard. In a self-hosted deployment, it answers with a model from the provider you choose, using your own API key. It runs on your CostGraph URL under `/graphai`.

## Before you begin

* An API key from a model provider, such as Anthropic, OpenAI, or OpenRouter.
* Access to run SQL as the user that owns the CostGraph database.
* If your Postgres requires TLS, the CA certificate that signs it.

## Turn on Graph AI

**1. Create a read-only database login**

Graph AI queries your cost data with its own login. For that login, the database shows only the rows of the tenant being asked about. Graph AI does not start without it.

Run this as the database owner. Replace the password, database name, and owner.

```sql theme={null}
CREATE ROLE costgraph_reader LOGIN PASSWORD '<a strong password>';
GRANT CONNECT ON DATABASE <database> TO costgraph_reader;
GRANT USAGE ON SCHEMA public TO costgraph_reader;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO costgraph_reader;
ALTER DEFAULT PRIVILEGES FOR ROLE <owner> IN SCHEMA public
  GRANT SELECT ON TABLES TO costgraph_reader;
REVOKE SELECT ON public.graphai_run_credentials,
                 public.k8s_workload_savings,
                 public.network_edges_resolved
  FROM costgraph_reader;
```

**2. Store the key and the login in a Secret**

Name the key variable after your provider. See [Choose a model](#choose-a-model).

```shell theme={null}
kubectl create secret generic costgraph-graph-ai --namespace costgraph \
  --from-literal=ANTHROPIC_API_KEY=<your key> \
  --from-literal=COSTGRAPH_READ_DATABASE_URL='postgres://costgraph_reader:<password>@<host>:5432/<database>'
```

**3. Add Graph AI to your values file**

```yaml theme={null}
global:
  graphAi:
    enabled: true
graphAi:
  model: anthropic/claude-sonnet-4-5
  existingSecret: costgraph-graph-ai
```

Run `helm upgrade` with your values file. Graph AI appears in the dashboard after the upgrade finishes.

> [!NOTE]
>
> Graph AI connects with `global.postgres.url` exactly as written, so the URL must include the password.

## Choose a model

Set `graphAi.model` to `<provider>/<model>`, and name the key variable as your provider expects.

| Provider | Example `graphAi.model` | Key variable |
| - | - | - |
| Anthropic | `anthropic/claude-sonnet-4-5` | `ANTHROPIC_API_KEY` |
| OpenAI | `openai/gpt-5` | `OPENAI_API_KEY` |
| OpenRouter | `openrouter/anthropic/claude-sonnet-4.5` | `OPENROUTER_API_KEY` |
| Google | `google/gemini-2.5-pro` | `GOOGLE_GENERATIVE_AI_API_KEY` |
| Mistral, Groq, DeepSeek, xAI | `<provider>/<model>` | `<PROVIDER>_API_KEY` |

Pick a strong model. Graph AI calls many tools in a single answer, and small models give poor results.

### Use your own gateway

To send requests through a gateway such as LiteLLM, use an `openai/` or `anthropic/` model and add `OPENAI_BASE_URL` or `ANTHROPIC_BASE_URL` to the Secret. For `openai/` models, the gateway must support the OpenAI Responses API. This is also how you reach Azure OpenAI, Amazon Bedrock, or Google Vertex.

## Databases that require TLS

Graph AI checks your database's certificate whenever the connection uses TLS. Amazon RDS, Cloud SQL, and Azure Database use TLS by default, so give Graph AI the CA certificate.

```shell theme={null}
kubectl create secret generic costgraph-postgres-ca --namespace costgraph \
  --from-file=ca.pem=<your provider's CA bundle>
```

```yaml theme={null}
graphAi:
  deployment:
    volumes:
      postgres-ca:
        secret:
          secretName: costgraph-postgres-ca
    volumeMounts:
      postgres-ca:
        mountPath: /etc/ssl/certs/postgres
        readOnly: true
```

Then add `RDS_CA_PATH=/etc/ssl/certs/postgres/ca.pem` to the `costgraph-graph-ai` Secret. Amazon RDS publishes its bundle at `https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem`. A Postgres in your cluster without TLS needs `sslmode=disable` in `global.postgres.url`.

## Long answers

Graph AI streams its answers. If your ingress closes slow responses, long answers stop partway. On ingress-nginx, raise the timeouts.

```yaml theme={null}
ingress:
  annotations:
    nginx.ingress.kubernetes.io/proxy-read-timeout: "300"
    nginx.ingress.kubernetes.io/proxy-send-timeout: "300"
```

## Connect MCP clients

Claude Desktop, Cursor, and other MCP clients can read your costs through CostGraph's MCP server. It needs its own hostname.

```yaml theme={null}
graphAi:
  mcp:
    host: mcp.costgraph.internal.example.com
ingress:
  tls:
    - secretName: costgraph-tls
      hosts: [costgraph.internal.example.com, mcp.costgraph.internal.example.com]
```

Point the hostname at your ingress. Then add `https://mcp.costgraph.internal.example.com/` as a server in the MCP client.

Clients that support OAuth, such as Claude Desktop's custom connectors, open your CostGraph in the browser to sign you in. The client must be able to reach your CostGraph URL.

For clients without OAuth, use an API key.

1. In CostGraph, open **Settings > Personal API Keys** and create a key.
2. In the MCP client, add the header `X-API-Key: <your key>`.
3. If you belong to more than one tenant, also add `X-CostGraph-Tenant-ID: <tenant ID>`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.