Homespun — Claude Code MCP server: what it does, how to install
Deploys multi-user web applications straight from your AI coding agent, providing instant hosting, magic-link login, and a shared database.
claude mcp add --transport http homespun https://homespun.dev/mcpWhat Homespun does
This server connects your MCP host directly to the Homespun platform. Through the deploy_app tool, an agent ships an HTML document with a capability manifest to obtain a live URL equipped with role permissions, email alerts, and asset storage.
Data lives inside mutable collections where rows track keys, data payloads, author IDs, and optimistic locking versions. Because MCP runs on request-response turns, agents inspect updates by polling get_feed_events or using long-polling with a wait parameter.
Running the binary locally requires Node.js 20 or newer. When launched without an API key, it registers a fresh agent profile against the relay and writes credentials to ~/.config/homespun/config.json.
What it helps with
- Publish a web application to its own URL using the
deploy_apptool - Store and update application records with optimistic locking
- Manage app members and role assignments through unified actions
- Poll change feeds to inspect writes from human users
Example prompts for the agent
- Deploy the application defined in
app.htmlto a public URL - Insert a new record into the collection using
add_row - Check for recent changes across data rows by polling
get_feed_events
How to install Homespun
1Platform CLI: remote server
claude mcp add --transport http homespun https://homespun.dev/mcp2Platform CLI
claude mcp add --env HOMESPUN_API_KEY=<HOMESPUN_API_KEY> --env HOMESPUN_URL=<HOMESPUN_URL> --env HOMESPUN_AGENT_NAME=<HOMESPUN_AGENT_NAME> --env HOMESPUN_REGISTER_SECRET=<HOMESPUN_REGISTER_SECRET> --transport stdio mcp -- npx -y @homespunapps/mcpReplace <…> with your own values
1Platform CLI: remote server
codex mcp add mcp --url https://homespun.dev/mcp2Platform CLI
codex mcp add mcp --env HOMESPUN_API_KEY=<HOMESPUN_API_KEY> --env HOMESPUN_URL=<HOMESPUN_URL> --env HOMESPUN_AGENT_NAME=<HOMESPUN_AGENT_NAME> --env HOMESPUN_REGISTER_SECRET=<HOMESPUN_REGISTER_SECRET> -- npx -y @homespunapps/mcpReplace <…> with your own values
Config file
{
"mcpServers": {
"mcp": {
"url": "https://homespun.dev/mcp"
}
}
}{
"mcpServers": {
"mcp": {
"command": "npx",
"args": [
"-y",
"@homespunapps/mcp"
],
"env": {
"HOMESPUN_API_KEY": "<HOMESPUN_API_KEY>",
"HOMESPUN_URL": "<HOMESPUN_URL>",
"HOMESPUN_AGENT_NAME": "<HOMESPUN_AGENT_NAME>",
"HOMESPUN_REGISTER_SECRET": "<HOMESPUN_REGISTER_SECRET>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"mcp": {
"type": "http",
"url": "https://homespun.dev/mcp"
}
}
}{
"servers": {
"mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@homespunapps/mcp"
],
"env": {
"HOMESPUN_API_KEY": "<HOMESPUN_API_KEY>",
"HOMESPUN_URL": "<HOMESPUN_URL>",
"HOMESPUN_AGENT_NAME": "<HOMESPUN_AGENT_NAME>",
"HOMESPUN_REGISTER_SECRET": "<HOMESPUN_REGISTER_SECRET>"
}
}
}
}Replace <…> with your own values
1Platform CLI: remote server
gemini mcp add -t http mcp https://homespun.dev/mcp2Platform CLI
gemini mcp add -e HOMESPUN_API_KEY=<HOMESPUN_API_KEY> -e HOMESPUN_URL=<HOMESPUN_URL> -e HOMESPUN_AGENT_NAME=<HOMESPUN_AGENT_NAME> -e HOMESPUN_REGISTER_SECRET=<HOMESPUN_REGISTER_SECRET> mcp npx -y @homespunapps/mcpReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Homespun
How to install Homespun in Claude Code?
Add the remote endpoint using this command in your terminal: claude mcp add --transport http homespun https://homespun.dev/mcp.
What are the runtime requirements for Homespun?
Running the server via stdio requires Node.js 20 or higher. You do not need to register an API key in advance, because the server creates an agent identity on its first run.
How does Homespun sync data without persistent sockets?
The client polls get_feed_events by passing the cursor from the previous call. It also supports long-polling when you specify a wait duration up to 30 seconds.
