A complete guide to scaffolding an MCP server with NitroStack, testing it visually in NitroStudio, and submitting it to the official Anthropic MCP Directory — so Claude users everywhere can discover and connect to your app.
Anthropic runs an official MCP Directory — a curated list of connectors that Claude users can install in one click from Claude.ai, Claude Desktop, and Claude Mobile. NitroStack gets your MCP server directory-ready, fast.
The Model Context Protocol (MCP) isn't just a developer experiment anymore. Anthropic has built a fully supported app ecosystem around it — and the Anthropic MCP Directory is how users discover and connect to third-party MCP servers directly from Claude, with no manual setup required.
Getting into that directory means building to a standard: proper tool annotations, HTTPS deployment, OAuth 2.0, and comprehensive documentation. It sounds like a lot — but NitroStack's framework handles the structural complexity, and this guide walks you through every requirement clearly.
Here's what this tutorial covers:
- Scaffold an MCP server using the NitroStack CLI
- Configure it for Claude MCP App mode
- Add safety annotations required for directory submission
- Test your app in NitroStudio and with third-party MCP inspectors
- Deploy to NitroCloud for a production HTTPS URL
- Submit to the Anthropic MCP Directory
Claude MCP Apps vs ChatGPT Apps
Claude MCP Apps and ChatGPT Apps share the same underlying protocol, but the distribution model is fundamentally different. Understanding this upfront shapes every decision in this guide.
ChatGPT Apps
Self-registered per user — developers generate a URL, users paste it in. Fast to test, but no centralized discovery. Each user adds the app manually through their own ChatGPT settings.
Claude MCP Apps
Submitted once, available to all Claude users via the official directory. One-click connect from claude.ai/connectors. Reviewed and vetted by Anthropic before listing.
The trade-off is clear: Claude MCP Apps require more upfront preparation, but the payoff is distribution across every Claude platform — web, desktop, mobile, and API — with zero user friction.
Prerequisites
Node.js>= 18.0.0
npm>= 9.0.0
NitroCloudFor HTTPS deploy
node -v
npm -v
Step 01 — Install the NitroStack CLI
Install the CLI globally.
npm install -g @nitrostack/cli
Confirm the installation succeeded:
nitrostack-cli --help
The CLI help menu should print cleanly. If it does, you're ready to scaffold.
Step 02 — Initialize a New MCP Project
nitrostack-cli init pizza-shop-finder
When prompted to choose a template, select:
Advanced TemplatePizza Shop Finder with Maps and Widgets
This template ships with working MCP tools, UI widgets, and sample data — everything needed to demonstrate a real end-to-end app during testing and Anthropic's review.
Provide a project description when prompted:
An MCP app for pizza shops where consumers can find andpurchase their favorite pizza through AI models
Enter your name as the author. The CLI scaffolds the full project structure automatically.
Step 03 — Open the Project in Your Editor
# VS Codecode pizza-shop-finder
# Cursorcursor pizza-shop-finder
NitroStack uses a module-based architecture. Your MCP tools, services, data, and widgets are organized into separate modules from the start — clean and ready to scale.
Step 04 — Add Safety Annotations to Your Tools
This step is mandatory for Anthropic directory submission. Every tool in your MCP server must declare a safety annotation. Without it, your submission will be rejected immediately.
Open your tools file:
src/modules/pizza/pizza.tools.ts
NitroStack's @Tool decorator accepts annotation fields directly. Here's how to apply them correctly:
// ✅ Read-only tool — only fetches data@Tool({ name: "show_pizza_list", description: "Returns the list of available pizzas", annotations: { readOnlyHint: true, destructiveHint: false, title: "Show Pizza List" }})async showPizzaList() { ... }// ✅ Write tool — creates or modifies data@Tool({ name: "order_pizza", description: "Places a pizza order for the user", annotations: { readOnlyHint: false, destructiveHint: true, title: "Order Pizza" }})async orderPizza(input: OrderInput) { ... }
Use this table to decide which annotation applies to each of your tools:
Tool Behavior
Correct Annotation
Examples
Only reads data
readOnlyHint: true
search, get, list, fetch, read
Writes or modifies data
destructiveHint: true
create, update, delete, send
Sends external requests
destructiveHint: true
emails, webhooks, notifications
Creates temporary files
destructiveHint: true
Even temp writes count
⚠️ Hard requirement. Anthropic's review process checks every single tool for these annotations. Missing even one will result in an immediate rejection. Annotate all tools before deploying.
Step 05 — Configure Claude MCP Mode & Start the Server
Open the .env file at the project root and set the app mode. NitroStack supports two options for Claude MCP Apps:
# Use this for a Claude-only MCP AppNITROSTACK_APP_MODE=mcp-app
# Or use this to support both Claude AND ChatGPT from one serverNITROSTACK_APP_MODE=universal
💡 Which mode should I choose? Use mcp-app if you're building exclusively for Claude. Use universal if you want the same NitroStack server to power both a Claude MCP App and a ChatGPT App simultaneously — one codebase, two ecosystems.
Start the server:
npm run start
The server starts on port 3000. Your MCP endpoint is live at http://localhost:3000/sse.
Step 06 — Test Your MCP App
Before deploying or submitting, verify that your tools work correctly. You have two excellent options for this.
Option A — NitroStudio (Recommended)
Download NitroStudio and open your project. In the Chat panel, you'll find a mode toggler that lets you switch between ChatGPT mode and MCP (Claude App) mode. Switch it to MCP mode to simulate exactly how Claude will interact with your server.
In MCP mode, type a test prompt like Show pizza list and NitroStudio will execute the MCP tool call, show you the full request/response trace, and render the widget — identical to what Claude will do.
Anthropic's review team will test your server end-to-end. Verifying tool execution, error handling, and annotation accuracy before submitting significantly reduces back-and-forth in the review process.
Step 07 — Deploy to NitroCloud
The Anthropic MCP Directory requires a production-grade HTTPS endpoint — a localhost URL will not be accepted. Deploy your MCP server to NitroCloud to get a stable, permanent HTTPS URL with zero infrastructure to manage.
Your deployed server URL will follow this format:
https://your-app.nitrocloud.app/sse
This is the URL you'll reference in your documentation, test account instructions, and the submission form.
🔒 Firewall note: If your NitroCloud server is behind a custom firewall, you'll need to allowlist Anthropic's IP addresses. NitroCloud's default configuration does not require this.
Step 08 — Prepare Your Submission Materials
Anthropic reviews every submission manually. The quality of your documentation directly affects how quickly your app gets approved. Incomplete submissions are the number one cause of rejection and revision requests.
You'll need to prepare the following before filling out the form:
Submission Checklist
- Server description and feature listWhat your server does and why it's useful to Claude users [REQUIRED]
- Minimum 3 usage examplesReal prompts with expected outputs — covering different tools and capabilities [REQUIRED]
- Safety annotations on every toolreadOnlyHint or destructiveHint must be set on ALL tools [REQUIRED]
- Privacy policy at a stable HTTPS URLA publicly accessible privacy policy page for your app [REQUIRED]
- Dedicated support channelEmail address or support URL where users can get help [REQUIRED]
- Test account with sample dataIf your server requires authentication — include credentials in the form [IF AUTH]
- OAuth 2.0 implementationMust use the authorization code flow. Callback URLs must include Claude's redirect URIs [IF AUTH]
- Production-ready deployment (GA status)No beta or development servers — must be stable and fully functional [REQUIRED]
OAuth Callback URLs (if authentication required)
If your app requires authentication, your OAuth provider must have these Claude redirect URIs allowlisted:
# Local MCP client callbackshttp://localhost:6274/oauth/callbackhttp://localhost:6274/oauth/callback/debug
# Claude production callbackshttps://claude.ai/api/mcp/auth_callbackhttps://claude.com/api/mcp/auth_callback
What good usage examples look like
Anthropic requires a minimum of three examples, each showing a realistic user prompt and what actually happens when the tool runs. Here's the format:
### Example 1: Browse Available Pizzas**User prompt:** "Show me the pizza menu"**What happens:**- Server calls show_pizza_list tool- Returns pizza catalog with names, descriptions, prices- Renders an interactive widget in the Claude UI
### Example 2: Find a Pizza Shop Nearby**User prompt:** "Find pizza shops near downtown San Francisco"**What happens:**- Server calls find_pizza_shop with location- Returns nearby locations with map data- Renders a map widget with shop markers
### Example 3: Place an Order**User prompt:** "Order a large Margherita for delivery"**What happens:**- Server calls order_pizza with item and size- Confirms order details and returns order ID- Provides delivery time estimate
Step 09 — Submit to the Anthropic MCP Directory
With your server deployed, annotations in place, and documentation ready, you can submit to Anthropic for review. They review every submission manually — complete submissions move through the process significantly faster.
📋 Before submitting, read Anthropic's official Remote MCP Server Submission Guide to verify you've met every current requirement. Standards evolve as the directory grows.
When ready, submit using the official form:
MCP Directory Server Review Form →
After submission, Anthropic will review your server for quality, security, and compliance with their MCP Directory Policy. Once approved, your app will appear at claude.ai/connectors and be available for one-click installation across all Claude platforms.
ℹ️ Review timeline: Anthropic processes submissions as quickly as possible but cannot guarantee individual responses due to volume. Servers with complete documentation and no missing requirements typically move through faster. There is no SLA for initial review.
What Happens After Approval
Claude MCP App user journey
User visits claude.ai/connectors → Finds your app in directory → One-click connect → OAuth flow (if required) → Claude calls MCP tools in chat
Once listed, your MCP server becomes a first-class connector in Claude — available across the web app, Claude Desktop, and Claude Mobile with no additional configuration from users. Claude can discover and call your tools automatically in any relevant conversation.
Keep your server healthy post-launch. Anthropic monitors listed servers and may remove apps that become unstable, unresponsive, or fall out of compliance with updated policies. Set up monitoring and alerting on your NitroCloud deployment from day one.
Common Rejection Reasons to Avoid
These are the most frequent reasons Anthropic sends revision requests, based on their published submission guidance:
- Missing tool annotations — every tool needs readOnlyHint or destructiveHint. No exceptions.
- Fewer than 3 usage examples — the minimum is three, and they must demonstrate real tool functionality, not just describe it.
- OAuth callback URLs not configured — Claude's redirect URIs must be allowlisted in your OAuth provider before submission.
- Privacy policy URL is inaccessible — the link must resolve publicly over HTTPS. No login walls, no localhost.
- Server marked as beta — Anthropic requires GA status. "Coming soon" features or known instability will block approval.
- No dedicated support channel — a valid email address or support URL is required. Personal social media handles don't qualify.
What You Just Built
Starting from zero, you've gone through every step to get a production MCP server into the Anthropic directory:
- Scaffolded a full MCP server with the NitroStack CLI
- Applied safety annotations to all tools — the most common rejection reason, addressed upfront
- Configured Claude MCP App mode with a single environment variable
- Tested the full tool execution flow in NitroStudio's MCP mode and via mcpjam.com
- Deployed to NitroCloud for a production HTTPS endpoint
- Assembled all required submission materials and submitted to the Anthropic MCP Directory
Where to Go from Here
The pizza shop template is intentionally simple. Once you're familiar with the submission flow, you can build on top of NitroStack with:
- Real data sources — replace static data with live database queries or third-party API calls
- OAuth integration — NitroStack has built-in OAuth middleware for protecting tools behind user authentication
- Custom widgets — build rich UI components that render inside Claude's interface via NitroChat's widget layer
- Universal mode — ship the same server to both the Claude MCP Directory and as a ChatGPT App with NITROSTACK_APP_MODE=universal
Build for the Anthropic MCP Directory
NitroStack handles the protocol. You focus on the product.