Val Town MCP Server
Official hosted MCP server for vals, JavaScript execution, deployments, logs, and SQLite from an AI client.
- Skill Road
- Val Town MCP Server
Categories
Description
The Val Town MCP Server is Val Town’s official hosted Model Context Protocol endpoint. It connects an MCP-capable AI client to an account on the Val Town platform. The official MCP guide identifies https://api.val.town/v3/mcp; the current official repository for agent plugins is https://github.com/val-town/plugins. That repository registers the same hosted endpoint for Claude Code, Codex, and Cursor and describes itself as the source of the platform skills. The MCP server is therefore a Val Town product, not an independent community connector.
Purpose and documented capabilities
According to Val Town, a “val” is a collaborative, versioned folder of runnable code: similar to a repository that can run. Vals use JavaScript in the Deno runtime and can use HTTP, cron, and email triggers, SQLite, blob storage, environment variables, logs, and traces. The MCP documentation suggests asking the model to list or examine vals, read SQLite data and logs, and edit vals. It also explicitly describes agentic iteration: a model can change code, inspect output and logs, then continue. New or changed vals are deployed through the platform; HTTP endpoints, cron jobs, and email handlers are documented execution forms. For larger work, however, Val Town recommends feature branches and merging when stable. Every file change is versioned, and the Versions or History interface supports rollbacks.
Setup and access tokens
The documented direct setup for Claude Code is claude mcp add --transport http val-town https://api.val.town/v3/mcp. Then confirm the connection in the client and complete the browser OAuth flow when required. The official plugin is the preferred route because it bundles the server and platform skills; Val Town documents claude plugin install valtown@claude-plugins-official for Claude Code. The official repository also documents installation paths for Codex and Cursor. MCP access authenticates through OAuth, rather than by pasting a long-lived API token into a prompt. Separately, Val Town’s REST API supports Bearer tokens. Those tokens are managed on the API Tokens page and, according to the documentation, are scoped to the permissions granted. A token is a secret: issue it with the least required privilege, keep it in secure client configuration or a secret store, never put it in Git, logs, screenshots, or chat messages, and revoke it if exposure is suspected.
Secrets, visibility, and mutation
Environment variables are the documented location for passwords, tokens, and similar val secrets. Val Town explicitly says vals cannot set environment variables programmatically; Deno.env.set is a no-op for that purpose. This does not authorize reflecting secrets from untrusted input into code or output. A model with MCP write permissions can change source code and can therefore indirectly alter how existing secrets are handled. Review the diff, target val, branch, and trigger before every mutation. Vals may be public, unlisted, or private. “Unlisted” is not access control; use private visibility and appropriate collaborator permissions for confidential source and data. Public HTTP endpoints also need their own authentication, such as OAuth, Basic Auth, or login logic, when the application should not be open.
Client-to-model data path and security boundaries
The practical path is: a user states a task in an AI client; the client sends an MCP tool call to the Val Town endpoint; Val Town authorizes and processes it against the account; structured results such as val metadata, code, logs, or SQLite results return to the client. The client may pass those tool results to the selected model as context. A hosted MCP server therefore does not mean data stays only between the client and Val Town: what is also sent to the model provider depends on the client, model, that provider’s privacy and retention terms, and selected settings. Do not place secrets, personal SQLite records, or unreviewed third-party text into model context.
Prompt injection and responsible operation
Logs, comments, web content, emails, and SQLite fields can contain untrusted text. Such text can try to induce instructions such as “ignore previous instructions,” secret exfiltration, or deployment changes. It is data, not an authority source. Limit MCP permissions, use branches for changes, begin with read-only operations, and deliberately approve every write, deployment, or rollback. Immediately before this seed on 2026-09-08, the GitHub API reported exactly 10 stars for val-town/plugins. That is only a point-in-time repository-popularity signal, not an audit or a security or quality judgement.
Requirements
Val Town account, compatible MCP client, and OAuth consent; use API tokens for the REST API only with least privilege.
Installation instructions
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.
Step 1: 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.
Step 2: 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.
claude mcp add --transport http val-town https://api.val.town/v3/mcp
claude plugin install valtown@claude-plugins-official
Step 3: 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.
Step 4: 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.
Authentication
OAuth for the MCP server. REST API tokens are separate scoped Bearer tokens and do not belong in prompts.
Required access permissions
Depending on OAuth consent, the MCP server can read vals, code, logs, and SQLite and mutate vals; restrict write access deliberately.
Transmitted or stored data
MCP results travel from Val Town back to the AI client. The client may send them to the selected model as context; also review model-provider rules.
Security risks
Code mutations and deployments, access to logs/SQLite, token or secret exposure, and prompt injection from untrusted tool content.
License and costs
- License
- MIT
- Cost
- free
The official plugin source is MIT licensed. Account use and the AI client may have their own terms; check Val Town for current details.
Alternatives
Not recorded yet.
At a glance
- Provider
- Val Town
- Status
- Official server
- Deployment
- Remote
- Current version
- Not recorded yet.
- GitHub stars
- 10
- Last reviewed
- 08.09.2026
Repository and documentation
Categories
Supported clients
Related guides
Guides and background related to this entry.