Build MCP Apps

View saved version →

---
name: build-mcp-apps
description: Guide developers through creating and updating MCP servers, MCP apps, and ChatGPT apps with Skybridge. Covers brainstorming, bootstrapping, implementing tools/views, debugging, running dev servers, and preparing apps for deployment. Use when a user wants to create or update a ChatGPT app, MCP app, MCP server, or use the Skybridge framework.
---

# Building MCP Apps

MCP apps are conversational experiences that extend AI assistants through tools and custom UI views. They are built as MCP servers invoked during conversations.

Important: The app is consumed by two users at once: the **human** and the **AI Assistant LLM**. They collaborate through the view-the human interacts with it, the LLM sees its state. Internalize this before writing code: the view is your shared surface.

Skybridge docs are the product source of truth. Use this skill's references for
agent workflow, and use `https://docs.skybridge.tech/` for canonical framework
behavior and API details.

SPEC.md keeps track of the app's requirements and design decisions. Keep it up to date as you work on the app.

**No SPEC.md?** -> Read [discover.md](references/discover.md) first. Nothing else until SPEC.md exists.

**SPEC.md exists?** -> Read SPEC.md, then follow [architecture.md](references/architecture.md) to design the change. Update SPEC.md, then read the relevant Implementation references below before writing code.

## Setup

1. **Copy template** -> [copy-template.md](references/copy-template.md): when starting a new project with ready SPEC.md
2. **Run locally** -> [run-locally.md](references/run-locally.md): when ready to test, need dev server, use devtools to render views, or connect to ChatGPT/Claude
3. **Use DevTools UI** -> [devtools.md](references/devtools.md): when testing tools/views through Skybridge DevTools, opening the Alpic playground, starting a tunnel, or deploying from the DevTools UI

## Architecture

Design or evolve UX flows and API shape -> [architecture.md](references/architecture.md)

## Implementation

- **Fetch and render data** -> [fetch-and-render-data.md](references/fetch-and-render-data.md): when implementing server handlers and view data fetching
- **State and context** -> [state-and-context.md](references/state-and-context.md): when persisting view UI state and updating LLM context
- **Prompt LLM** -> [prompt-llm.md](references/prompt-llm.md): when view needs to trigger LLM response
- **UI guidelines** -> [ui-guidelines.md](references/ui-guidelines.md): display modes, layout constraints, theme, device, and locale
- **External links** -> [open-external-links.md](references/open-external-links.md): when redirecting to external URLs or setting "open in app" target
- **Download file** -> [download-file.md](references/download-file.md): when saving content to the user's filesystem
- **OAuth** -> [oauth.md](references/oauth.md): when tools need user authentication to access user-specific data
- **CSP** -> [csp.md](references/csp.md): when declaring allowed domains for fetch, assets, redirects, or iframes
- **Hosting assets** -> [hosting-assets.md](references/hosting-assets.md): when a ChatGPT/MCP app needs static JS, CSS, images, or built UI assets hosted on Alpic

## Deploy

- **Prepare for production** -> [deploy.md](references/deploy.md): when the app is ready and needs a deployment handoff to `use-alpic`
- **Publish to app directories** -> [publish.md](references/publish.md): when ready to submit for review

## Skybridge Docs

- Docs home: [https://docs.skybridge.tech/](https://docs.skybridge.tech/)
- Full API reference: [https://docs.skybridge.tech/api-reference.md](https://docs.skybridge.tech/api-reference.md)
- Use the API reference when implementing server APIs, tools, views, resources,
  UI context, or SDK behavior that is not fully specified in these local
  references.

Referenced files: 16 — file references are metadata, not package contents.

View saved version →

---
name: use-alpic
description: Use Alpic Cloud and the `alpic` CLI for deployed MCP apps/servers, including deploys, builds, logs, debugging, environments, environment variables, tunnels, playgrounds, audits, auth, domains, IP restrictions, analytics, insights, versioning, and MCP Registry publishing.
---

# Alpic Cloud

Alpic hosts and operates MCP apps and servers. Use this skill for deployment,
runtime operations, distribution, security, observability, and publishing on
Alpic Cloud.

The reference files contain the task workflows and command details. Load only
the file(s) relevant to the user's request.

## When To Use

- The user mentions Alpic Cloud, `alpic`, Alpic deployments, Alpic logs, Alpic
  playground, Alpic tunnels, Alpic environments, or Alpic publishing.
- The user wants to operate an already-built MCP app/server.
- The user wants production/distribution guidance after building an MCP app.

Use `build-mcp-apps` instead when the work is primarily about designing or
implementing the MCP app/server itself.

## References

Deploy and operate:

- Deploy an MCP app/server: [deploy.md](references/deploy.md)
- Build configuration, runtimes, start commands: [builds.md](references/builds.md)
- Failed deploys and startup failures: [debug-deployment.md](references/debug-deployment.md)
- Runtime and deployment logs: [logs.md](references/logs.md)
- Environment variables: [environment-variable.md](references/environment-variable.md)
- Environments, branches, staging/preview/prod: [environments.md](references/environments.md)
- GitHub auto-deploys: [git.md](references/git.md)
- Local HTTPS tunnels: [tunnel.md](references/tunnel.md)

Inspect and test:

- Usage metrics and project analytics: [analytics.md](references/analytics.md)
- Readiness checks and launch audits: [audit.md](references/audit.md)
- Playground configuration and headers: [playground.md](references/playground.md)
- Playground example prompts: [example-prompts.md](references/example-prompts.md)
- Public URLs and endpoint shapes: [endpoints.md](references/endpoints.md)

Secure and distribute:

- OAuth, DCR proxy, API-key protection: [auth.md](references/auth.md)
- Fixed outbound IP and inbound IP whitelisting: [network-security.md](references/network-security.md)
- Custom domains and DNS validation: [domains.md](references/domains.md)
- User intents and feedback capture: [insights.md](references/insights.md)
- Host caching and submitted-version strategy: [versioning.md](references/versioning.md)
- MCP Registry publishing: [publish.md](references/publish.md)

## Interface Choice

- Prefer the `alpic` CLI for deploys, logs, environment variables,
  environments, git, tunnels, audits, playground settings, and publishing.
- Use the Alpic dashboard for custom domains, DCR client pools, fixed outbound
  IP, inbound IP whitelisting, visual analytics, and Beacon rendering checks.
- Use the hosted Alpic MCP server/app for agent-driven project browsing, logs,
  and analytics when available.
- Use REST APIs only for automation or gaps in CLI/MCP coverage.

## Guardrails

- Store secrets in Alpic environment variables, not source files.
- Confirm the target project and environment before changing production config,
  auth, domains, IP restrictions, fixed outbound IP, or environment variables.
- Use build/deployment logs for deploy failures and runtime logs for live
  behavior.
- Re-deploy after changing environment variables.
- Do not delete DCR client pools unless intentionally breaking existing client
  registrations.
- Publish only after a production deploy plus audit/playground verification.

Referenced files: 19 — file references are metadata, not package contents.