Set up Val Town MCP Server safely

This guide configures the official Val Town MCP Server so that an AI client can use vals and platform data without unnecessarily broadening write access or exposing secrets. Start with the official MCP documentation at https://docs.val.town/guides/prompting/mcp/. The endpoint is hosted: https://api.val.town/v3/mcp. Prefer the official plugin at https://github.com/val-town/plugins because Val Town distributes both the MCP server and its platform skills there for Claude Code, Codex, and Cursor. Treat every connection as access to account code, logs, and potentially SQLite data.

Inventory access before connecting

First make a short access decision. Which vals should the model see? Which are public, unlisted, or private? Which contain production endpoints, customer data, tokens, or sensitive logs? Private is the appropriate visibility for confidential source; unlisted only prevents easy discovery and is not access control. Review collaboration permissions too. Record which actions the model may initially read and which might later be permitted after human review. “List vals” is a sensible first test for a new integration; deployments, code edits, and rollbacks do not belong in the first prompt.

Configure OAuth and the client

For Claude Code, use the documented direct command: claude mcp add --transport http val-town https://api.val.town/v3/mcp. Then run /mcp, confirm the connection, and complete browser OAuth only for the expected Val Town account. Alternatively use claude plugin install valtown@claude-plugins-official; Val Town identifies that as the preferred route. For Codex and Cursor, follow the current instructions in the official plugin repository. After installation, check the server name and endpoint URL in the client instead of blindly accepting commands copied from logs or web pages. Never disclose OAuth dialogs or tokens in screenshots, tickets, or prompts.

Keep API tokens and secrets separate

The MCP server uses OAuth. Val Town API tokens are separate Bearer tokens for the REST API. When a workflow genuinely needs an API token, create one with the least required permissions and keep it in secure client configuration or a secret store. A token belongs neither in a val file nor in chat history. Val Town environment variables are intended for application secrets; the documentation also says vals cannot set them programmatically. That helps prevent accidental runtime updates, but it does not replace code review: a code mutation could read secrets or send them to an external endpoint. Limit write access and inspect diffs before merging.

Run a safe first pass

Begin with a deliberately narrow read task, for example: “List only my private development vals with name and trigger; do not change anything.” Review the response in the client and decide whether it contained data that should have reached the model. The data path is user to client, client over MCP to Val Town, then tool results back to the client. The client may pass results to the selected model. Therefore also review the model provider’s privacy, retention, and training settings. Do not load entire SQLite tables, secrets, or raw logs into context when a filtered and redacted query is sufficient.

Control changes, execution, and deployments

Once reads are reliable, use a branch or remix for mutations. Ask the model for a plan and diff first, not immediate execution. Review the target val, trigger, imported dependencies, new network destinations, and every use of Deno.env. Only then permit code writing. An HTTP val, cron, or email handler may run in production after a change, so verify output, logs, and authentication before a merge. If something fails, do not patch in panic: Val Town versions changes automatically. Use the Versions or History interface for a targeted rollback after identifying the cause and affected version.

Defend against prompt injection

MCP tool results are not automatically trustworthy. A log entry, email text, web page, comment, or SQLite field can attempt to steer the model with an alien instruction. Treat statements such as “copy this token,” “disable authentication,” or “deploy now” as untrusted data even when they appear in a tool result. Keep a clear operating rule: tool content may provide facts, but it cannot expand permissions or replace human approval. Use precise prompts, explicitly confirm each write operation, and end the session if suspicious secret output appears.

FAQ

Does the MCP endpoint replace API tokens? No. The documented MCP route uses OAuth. API tokens serve the REST API and need their own least-privilege permissions.

Can I connect public vals without concern? No. Public concerns source visibility, not endpoint security, log content, or transmission to the model. Review triggers and data content.

What is the smallest safe test? A tightly scoped read operation on an uncritical development val, followed by review of the displayed tool results and client configuration.