Skip to main content
Glama
robot-mcp-template

robot-mcp-template

by brianrenshaw

Your own MCP server: a starter

An MCP server is what lets a chat app such as Claude read and change your own data: your tasks, your recipes, your client list, your reading notes, whatever your project is about. You talk to the chat app; it uses the server to look things up and write things down.

This is a small, working one to start from. Out of the box it keeps notes, so there is something to try. You replace notes with your own thing.

What you get:

  • A server that runs on Cloudflare (the free plan is enough to start) with its own database.

  • Sign-in that only lets you in. Chat apps connect with a proper sign-in page; coding tools and scripts connect with a secret token.

  • It works with Claude on the web, the phone and the desktop app, and with Claude Code.

  • The habits that make a chatbot use a server well, already built in (see What we learned).

The quickest way: hand it to an AI

You do not have to write code. Press Use this template at the top of this page to make your own copy (choose Private if it will hold anything personal), open your copy in an AI coding tool such as Claude Code, and say something like:

Read CLAUDE.md first. This is a starter for an MCP server. I want mine to keep track of ______ (say what, in your own words, and what you want to ask your chatbot to do with it). Replace the notes example with that. Then walk me through the setup in the README one step at a time, doing every step you can do yourself.

CLAUDE.md tells the AI how the project is put together and which rules to keep. The steps below are the same ones it will follow, so you can also do them by hand.

Related MCP server: Expert Brain

What you need

  • A Cloudflare account.

  • Node.js 22 or newer on your computer (or an AI coding tool that has it).

  • A Claude plan that allows custom connectors, if you want to use it from the Claude app.

Setup

Step 1 was run exactly as written. Steps 2 to 8 were written from a working setup of the same design, not re-run on a brand-new Cloudflare account, so if Cloudflare's screens or commands have changed since, go by Cloudflare's current documentation.

1. Get the code and try it on your computer

npm install
cp .dev.vars.example .dev.vars
npm run migrate:local
npm run dev

The server is now running at http://localhost:8787. In a second terminal, check it:

npm run smoke
npm run smoke:oauth

Every line should say PASS. The first checks the token route, the second the sign-in that chat apps use. Nothing has left your computer yet.

2. Name it

In wrangler.jsonc, change my-mcp-server (the name and the database_name) to a name of your own, in lowercase with dashes. In src/index.ts, change SERVER_NAME to what you want chat apps to call it.

3. Create the database

npx wrangler login
npx wrangler d1 create my-mcp-server

Use your own name in place of my-mcp-server. The command prints a database_id. Put it in wrangler.jsonc in place of REPLACE-WITH-YOUR-DATABASE-ID. If it offers to add the database to your configuration for you, say no: it is already there. Then create the tables:

npm run migrate:remote

4. Deploy it once to learn its address

npm run deploy

It prints an address like https://my-mcp-server.your-subdomain.workers.dev. Put that address in wrangler.jsonc as PUBLIC_URL, with no slash at the end. It has to be exact: chat apps are told to sign in there.

5. Set the two secrets

A long random token, for Claude Code and scripts. Make one:

openssl rand -hex 32

Save it:

npx wrangler secret put MCP_TOKEN

And the email address that is allowed to sign in (yours):

npx wrangler secret put OWNER_EMAIL

Keep the token somewhere safe, such as a password manager. Anyone who has it can use your server. Never put it in a file in this repository.

6. Put the sign-in page behind Cloudflare Access

This is what makes the sign-in page yours alone. Cloudflare Access asks whoever opens the page to prove who they are (it emails a one-time code), and the server then checks that it was you.

In the Cloudflare dashboard, go to Zero Trust, then Access controls, then Applications. (The first time, Zero Trust asks you to pick a team name. The free plan is fine.)

  1. Create a new application of the self-hosted kind.

  2. Add a public hostname: your server's address from step 4, with the path authorize. So the application covers my-mcp-server.your-subdomain.workers.dev/authorize and nothing else.

  3. Add a policy that allows one email address: yours.

  4. Save it. Then open the application again and copy its Application Audience (AUD) tag.

Put two values in wrangler.jsonc:

  • ACCESS_AUD: the AUD tag you copied.

  • ACCESS_TEAM_DOMAIN: your team's address, your-team-name.cloudflareaccess.com.

Then deploy again:

npm run deploy

Two things to get right here:

  • Protect only the /authorize path. Do not turn on Access for the whole server (the "Cloudflare Access" switch in the Worker's own settings does that). The chat app itself has to reach the rest of the server without a browser, and it carries its own token for that.

  • Cloudflare moves these menus around. If the names above do not match what you see, look for "self-hosted application" in Cloudflare's Access documentation, or ask your AI tool to do this step with Cloudflare's API.

Until this step is done, the sign-in page refuses everyone. That is on purpose.

7. Connect it

Claude (web, phone, desktop). In a browser, go to claude.ai, open Settings, then Connectors, and add a custom connector. Give it a name and your server's address with /mcp on the end:

https://my-mcp-server.your-subdomain.workers.dev/mcp

Claude sends you to your sign-in page. Sign in with your email, then choose Allow. Add it on the website, not in the desktop app: the desktop app's dialog has failed where the website worked. Once added, it is available in the apps too.

Claude Code. With the token from step 5:

claude mcp add --transport http my-mcp-server https://my-mcp-server.your-subdomain.workers.dev/mcp --header "Authorization: Bearer YOUR-TOKEN"

8. Try it

Start a new chat and say "add a note that the setup works", then "what notes do I have?".

To check the deployed server from your computer:

MCP_URL=https://my-mcp-server.your-subdomain.workers.dev/mcp MCP_TOKEN=YOUR-TOKEN npm run smoke

Making it yours

The example is notes. Three files hold everything about notes, and those are the ones to change:

File

What it holds

migrations/0001_init.sql

The database tables. Add your own in a new file, 0002_...sql.

src/db.ts

Every database query.

src/tools.ts

What the chatbot can do (the tools) and what it is told (the instructions).

The rest (src/index.ts, src/authorize.ts, src/access.ts, src/kv.ts) is sign-in and plumbing. You should not need to touch it.

After any change: npm run typecheck, then npm run dev and npm run smoke, then npm run deploy. Start a new chat afterwards: chat apps remember a server's tools and instructions for the length of a chat.

What we learned

These came from building a server like this and using it every day. The starter already follows them.

  1. Few tools, exact descriptions. A chatbot picks worse among many look-alike tools. Before adding one, see whether an existing tool can answer. Every description says when to use the tool, with the words a person would actually say.

  2. Keep the instructions short. Chat apps cut long text without telling anyone. One was seen to keep only the first 4,096 characters of a server's instructions; some are reported to cut instructions and tool descriptions at 2,048. Stay under 4,000 and 2,000 (npm run smoke checks both), and put the most important lines first.

  3. Put a routine's rules where the routine starts. If one job needs a page of rules, return them in the result of the tool that job begins with (the example does this with how_to in list_notes). They arrive exactly when needed, and results are not cut.

  4. Every change answers with a receipt. One plain line saying what was done, for the chatbot to pass on. Otherwise it reads the whole record back to you.

  5. Never guess. When a name fits more than one thing, the tool returns the choices and the chatbot asks. A wrong guess written to your data is worse than a question.

  6. Search before adding. Tell the chatbot to look first, or you get duplicates.

  7. Never really delete. Mark things as removed so they can be brought back. People say "undo" to a chatbot the way they press Ctrl+Z.

  8. Tell it to read fresh every time. Without that, a chatbot answers from earlier in the chat and is confidently out of date.

  9. Record who wrote what. Each write is marked with the app that made it (mcp:claude), so you can tell what an AI changed.

  10. Fail closed. If sign-in is not set up, the answer is no. There is no "open for now".

  11. Keep the address stable. Changing the server's address means removing and re-adding the connector in every app.

When something goes wrong

  • The connector "couldn't be added". Add it on the claude.ai website, not the desktop app. Check that PUBLIC_URL is exactly the address you deployed to, with no slash at the end.

  • The sign-in page says sign-in is not set up. ACCESS_AUD, ACCESS_TEAM_DOMAIN or the OWNER_EMAIL secret is missing. Do steps 5 and 6, then deploy again.

  • "This account is not allowed." The email you signed in with is not the one in OWNER_EMAIL.

  • The chatbot does not see a new tool. Start a new chat.

  • To see what the server is doing: npx wrangler tail shows each request as it happens.

  • To sign every chat app out: empty the oauth_kv table. Each app then has to sign in again.

  • To change the token: npx wrangler secret put MCP_TOKEN with a new value, then update every tool that uses it.

What is in here

README.md                 this file
CLAUDE.md                 notes for the AI that changes this project
wrangler.jsonc            the server's settings (name, database, address)
migrations/               the database tables, in numbered files
src/index.ts              the front door: who gets in, where each request goes
src/authorize.ts          the sign-in page chat apps send you to
src/access.ts             checks that the person signing in is you
src/kv.ts                 keeps sign-in records in the database
src/db.ts                 every database query (the notes example)
src/tools.ts              the tools and the instructions (the notes example)
scripts/smoke.ts          checks the token route end to end
scripts/oauth-smoke.ts    checks the chat-app sign-in, on your computer only

No promises

This is shared as an example, as it is. Nobody is offering support for it. See LICENSE (MIT): you may use it and change it freely.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Gives Claude and other MCP clients remote, authenticated read/write access to a personal Obsidian vault over HTTPS — reading and atomically writing markdown, parsing YAML frontmatter, running indexed frontmatter queries and full-text search — behind OAuth 2.0 login (or Cloudflare Access) and a Cloudflare Tunnel that never exposes the host directly to the internet.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables Claude, Cursor, Codex, and any MCP client to search, read, write, and organize your existing notes and folders, with attachments, version history, and safe two-step edits guarded by diffs and base-version checks.
      385 npm
      1
      MIT