# TinyDB Remote MCP

A small, practical Model Context Protocol (MCP) server that stores data in
[TinyDB](https://tinydb.readthedocs.io/). It is designed as a learning project
for people who want to understand how to build an MCP server and connect it to
an MCP client.

The detailed, step-by-step project setup and deployment notes are in
[NOTES.md](NOTES.md).

## What this MCP does

The server exposes three tools:

- `insert_data` — stores one JSON document in TinyDB.
- `get_all_data` — returns every stored document.
- `delete_all_data` — removes every stored document.

For example, `insert_data` accepts:

```json
{
  "data": {
    "name": "Aarav Sharma",
    "email": "aarav.sharma@example.com",
    "role": "admin",
    "active": true
  }
}
```

## Run locally

This project uses [uv](https://docs.astral.sh/uv/) to manage dependencies.

```bash
uv sync
uv run python tinydb_remote_server.py
```

The local Streamable HTTP endpoint is:

```text
http://127.0.0.1:10000/mcp
```

TinyDB creates `db.json` at runtime. It is local runtime data and is not
intended to be committed to version control.

## Use the MCP

### MCP Inspector

Start the Inspector locally:

```bash
npx @modelcontextprotocol/inspector
```

Select **Streamable HTTP** and enter either the local endpoint above or your
deployed endpoint:

```text
https://<render-service-name>.onrender.com/mcp
```

You can also list the tools from the command line:

```bash
npx @modelcontextprotocol/inspector --cli https://<render-service-name>.onrender.com/mcp --transport http --method tools/list
```

### OpenAI web app

Enable Developer mode in ChatGPT under **Settings > Security and login**.
Then, from **Settings > Plugins** (or `https://chatgpt.com/plugins`), create
an app using your deployed MCP URL:

```text
https://<render-service-name>.onrender.com/mcp
```

After it is created, select the app in a ChatGPT project and ask it to insert
or retrieve test records.

### Codex, Claude web app, and Claude Code

Add the deployed `/mcp` URL as a Streamable HTTP MCP server in the client’s
MCP or connector settings. Once connected, the client can call
`insert_data`, `get_all_data`, and `delete_all_data`.

## Deployment and security notes

See [NOTES.md](NOTES.md) for the full Render deployment guide. When creating
the Render service, add `**/*.md` as an **Ignored Path** under **Advanced >
Build Filters** so Markdown-only changes do not trigger a deployment.

This example server is public and unauthenticated. Use test data only, and do
not store credentials, personal information, or other sensitive data. On
Render’s Free service, the TinyDB data is ephemeral and may be lost after a
restart or redeploy.