Chatgpt Postgres

chatgpt-postgres-mcp

The problem this solves

Ask ChatGPT to help you track something over time — applications, invoices, experiments — and you end up with a Markdown table it regenerates from scratch every conversation. Paste last week's table back in, it drops a row. Ask it to "sort by date applied" and it re-sorts the copy in front of it, not the record. There is no record.

A spreadsheet fixes the persistence and breaks everything else: the model can only see what you paste, and pasting 400 rows into a prompt is both expensive and lossy.

What you actually want is for ChatGPT to write INSERT and read SELECT against a table that outlives the chat. That is what this repository sets up, using a free PostgreSQL 16 instance from freebase.cloud exposed over MCP. Real DDL, real types, real JOINs, real aggregate functions — computed by Postgres, not approximated by a language model.

The worked example is a job-application tracker: three related tables, a few hundred rows at most, exactly the size of problem where a spreadsheet is annoying and a real database is overkill until it suddenly isn't.

---

Wiring it up

1. Create the instance. Sign up at freebase.cloud (free, no credit card), start a session, choose PostgreSQL. Nothing to size, nothing to wait for.

2. Get the MCP URL. In your dashboard: Settings → MCP → New Token → select the Postgres connection → copy. Shape:

   https://freebase.cloud/api/mcp/YOUR_TOKEN
   

   The credential is the path segment, so no header configuration appears anywhere below.

3. Note your connection name. It prefixes every tool. Throughout this README it is pg.

4. Register it in ChatGPT. Settings → Apps → Advanced settings → enable developer mode → Apps → Create → paste the URL → Auth: None → Scan Tools → Create. Read the plan caveat first; the menu location is genuinely ambiguous right now.

5. Turn it on in a chat. The + button in the composer, under Connectors. Then create the schema:

   Create three tables in my Postgres database: applications, interviews, contacts. Use the DDL in this message exactly. [paste examples/schema.sql]

   Expected:

   [pg_store] CREATE TABLE applications ... OK
   [pg_store] CREATE TABLE interviews ... OK
   [pg_store] CREATE TABLE contacts ... OK
   
   Three tables created. applications has a UNIQUE constraint on (company, role),
   so re-applying to the same posting will be rejected rather than duplicated.
   

---

The schema

Full DDL lives in examples/schema.sql and runs unmodified against an empty PostgreSQL 16 instance. The shape:

CREATE TABLE applications (
  id           SERIAL PRIMARY KEY,
  company      TEXT NOT NULL,
  role         TEXT NOT NULL,
  source       TEXT,                      -- referral | board | recruiter | direct
  applied_on   DATE NOT NULL DEFAULT CURRENT_DATE,
  status       TEXT NOT NULL DEFAULT 'applied',
  salary_min   INTEGER,
  salary_max   INTEGER,
  location     TEXT,
  remote       BOOLEAN DEFAULT false,
  notes        TEXT,
  UNIQUE (company, role)
);

Plus interviews (one-to-many off applications) and contacts. Ordinary relational design — the point is that ChatGPT can JOIN across them, and that the constraints stop it from writing nonsense. A CHECK on status means a hallucinated 'maybe?' fails loudly instead of silently polluting your data. Let the database be the adult in the room.

---

Annotation: the step everyone skips

pg_annotate_table attaches a plain-English description to a table. The model reads it before writing SQL. This is the single highest-leverage thing in this repo, and it takes two minutes.

Without it, on a fresh conversation:

You: what's my average salary expectation? Model: SELECT AVG(salary_min) FROM applications; → 78,400

Which is wrong in a way that looks right. salary_min is the bottom of the posted band, not your expectation, and it is NULL for every posting that did not publish one — so the average silently excludes half your rows.

After annotating:

You: what's my average salary expectation? Model: salary_min/salary_max are the posted band, not your target, and 22 of 41 rows have no band at all. Of the 19 postings that published one, the midpoints average 81,200. Your own target isn't stored anywhere — want me to add a column?

Same database, same question. The difference is one annotation.

Run it once per table:

Annotate applications: one row per posting applied to. status moves through applied → screening → onsite → offer → rejected → withdrawn and nothing else. salary_min/salary_max are the employer's posted band in USD, NULL when unpublished — never treat NULL as zero. source is how I found it. applied_on is submission date, not posting date.

Then interviews and contacts. Annotations persist on the connection, so every future chat — and every other MCP client pointed at the same token, Claude included — inherits them.

---

What the model does with it

A short transcript, three weeks in.

You: How many applications are still live, and where are they stuck?

[pg_query]
  SELECT status, count(*) FROM applications
  WHERE status NOT IN ('rejected','withdrawn') GROUP BY status ORDER BY 2 DESC;

  screening  7
  applied    5
  onsite     2

You: Anything I applied to more than three weeks ago that never moved past 'applied'?

[pg_query]
  SELECT company, role, applied_on, CURRENT_DATE - applied_on AS days_cold
  FROM applications
  WHERE status = 'applied' AND applied_on < CURRENT_DATE - INTERVAL '21 days'
  ORDER BY days_cold DESC;

  Northwind Labs   Backend Engineer   2026-07-14   35
  Acme Data        Platform Engineer  2026-07-22   27

You: Do referrals actually convert better than job boards for me?

[pg_query]
  SELECT source,
         count(*) AS total,
         count(*) FILTER (WHERE status IN ('onsite','offer')) AS advanced,
         round(100.0 * count(*) FILTER (WHERE status IN ('onsite','offer')) / count(*), 1) AS pct
  FROM applications GROUP BY source HAVING count(*) >= 3 ORDER BY pct DESC;

  referral   6   3   50.0
  direct     9   2   22.2
  board     21   2    9.5

That last one is the argument for SQL over a chat table. FILTER, HAVING, and integer-division-avoidance are all things the hosted Postgres 16 server does correctly and a model eyeballing a pasted table does not.

---

Tool reference

Tool	What it does
pg_query	Executes a read query and returns rows
pg_store	Writes — INSERT, UPDATE, and the DDL that creates your tables
pg_list_tables	Lists tables in the connection
pg_annotate_table	Stores the human description described above

PostgreSQL connections additionally surface pg_dump, pg_restore and pg_tables helpers. pg_dump is the one to remember — it is how you get a plain-SQL copy of everything out, and you should take one periodically.

---

Before you file a bug: the plan situation

OpenAI documents this feature in two places and the two disagree about the menu path. Check both:

• Settings → Apps → Advanced settings
• Settings → Connectors

One of them will have it in your build. As for entitlements: developer mode for custom MCP servers is documented for Pro, Plus, Business, Enterprise and Edu, and full write access is currently rolling out to Business, Enterprise and Edu workspaces. So a plausible outcome today is that ChatGPT happily runs pg_query and declines pg_store. That is the rollout, not your token.

Do not work around it by loosening anything. Either use the API path below, which is unaffected, or point a different MCP client at the same URL — Claude Desktop accepts the identical endpoint. The connection is not owned by ChatGPT.

ChatGPT requires the streamable HTTP transport; that is what this endpoint speaks. The older HTTP+SSE transport is deprecated and not in play.

---

From the Responses API

{
  "model": "gpt-5.6",
  "tools": [{
    "type": "mcp",
    "server_label": "pg",
    "server_description": "Job-application tracker: applications, interviews, contacts (PostgreSQL 16).",
    "server_url": "https://freebase.cloud/api/mcp/YOUR_TOKEN",
    "require_approval": "never"
  }],
  "input": "Which companies have I interviewed with twice or more without an offer?"
}

examples/pipeline_report.py runs a batch of these questions with no dependencies beyond the standard library; examples/log_application.mjs shows the write side and turns approvals back on to demonstrate the safer default. Both talk to the same free instance the chat client does. Keep require_approval enabled whenever the prompt text comes from someone who is not you — a tool that can INSERT can be talked into it.

---

Reaching the same database from psql

PostgreSQL is one of three engines exposed over the real TCP wire protocol, so the endpoint you created earlier is not a walled garden:

psql "postgresql://freebase@HOST:5432/mydb"

Prisma, Drizzle, SQLAlchemy, ActiveRecord, Knex, pgx, DBeaver, pgAdmin — anything speaking libpq connects unmodified. Window functions, CTEs and recursive queries, JSONB with GIN indexes, EXPLAIN ANALYZE, savepoints, serializable isolation, and extensions such as uuid-ossp, pgcrypto, hstore and citext all behave as the PostgreSQL 16 manual says.

The practical version of this: seed with psql, review with ChatGPT, export with pg_dump. One dataset, three doors.

---

Where this is the wrong tool

• Anything with a compliance story. The free tier targets development, prototyping and small production workloads. No SLA, backup schedule or uptime figure is published, and this README will not invent one.
• Bulk loading. Pushing 100k rows through a language model is absurd. Use psql \copy.
• Secrets. The token in the URL is the whole credential. Treat it like a password: not in commits, not in screenshots, rotate it in Settings → MCP if it escapes.
• Unattended writes on shared data. Models misread intent. Approvals exist for a reason.

---

FAQ

Does the model see my whole table on every question? No. It writes a query; Postgres returns only the result set. That is why aggregate questions stay cheap even as the table grows.

Can it drop my tables? pg_store executes DDL, so in principle yes. Keep approvals on for destructive phrasing, and take pg_dump snapshots.

Do I have to use the annotate tool? No, and you will regret it. It is the difference between a query that is syntactically valid and one that answers your actual question.

Will the same token work in Claude, Cursor or VS Code? Yes — one streamable-HTTP endpoint, many clients. See the Claude walkthrough for that path.

Is this a real Postgres or an emulation? Real PostgreSQL 16.2, wire-protocol compatible. Your ORM cannot tell the difference, which is the test that matters.

---

Files

Path	What it is
examples/schema.sql	The three-table DDL, seed rows, and the annotation prompts
examples/pipeline_report.py	Python, stdlib only — runs a set of analyst questions via Responses API
examples/log_application.mjs	Node, openai SDK — the write path, with approvals demonstrated
examples/README.md	How to run them and what output to expect

Links

• Free PostgreSQL cloud instance
• How to connect Claude to PostgreSQL
• PostgreSQL 16 documentation
• MCP specification
• OpenAI Responses API reference

MIT. Contributions welcome — especially additional annotation examples, which generalise well beyond job hunting.

freebase.cloud is an independent service and is not affiliated with OpenAI, Anthropic, or the PostgreSQL Global Development Group.