Documentation — MCP Hub

01 // QUICKSTART

Run the beast locally.

You need Node.js 20+, pnpm 9.12+, Git, and MySQL 8 or a compatible hosted database. The client and backend start separately; pretending one command starts both is how documentation becomes fan fiction.

1. Clone and install

git clone https://github.com/CassieMarie0728/mcp-hub.git
cd mcp-hub
pnpm install

2. Configure your environment

cp .env.example .env

Edit .env with a reachable MySQL connection and unique secrets. Do not commit it. GitHub already has enough accidental confessionals.

3. Initialize the database

pnpm db:push

4. Start the backend

pnpm dev:server

5. Start the Expo client

pnpm dev

The backend defaults to http://localhost:3000. Expo web defaults to http://localhost:8081. For a physical device, use your computer's LAN address instead of localhost.

Development only: Keep the service private while testing. Production mode requires real authentication, unique secrets, HTTPS, a least-privilege database account, and considerably less optimism.

02 // CONNECTIONS

Connect one server. Know what happened.

The managed connection flow is built around workspace-owned, standard-port HTTPS endpoints. It validates the destination, stores credentials as an encrypted envelope, and runs an explicit connection test.

Open the server connection screen in the app.
Give the connection a useful name.
Enter an https:// MCP endpoint on port 443 or omit the port.
Choose no auth, bearer token, API key, or custom headers as required by the server.
Save the connection, then run the test.

Outbound policy: Loopback, private-network, link-local, metadata, and non-HTTPS destinations are rejected by the managed remote flow. This is intentional SSRF protection, not the app being moody.

Never place credentials in the endpoint URL. Use the authentication fields so secrets can be encrypted and scoped correctly.

03 // TOOL DISCOVERY

Find out what the server can actually do.

After a successful connection, open Tool Discovery. The app requests the server's tool list through the authorized backend runtime and presents names, descriptions, and input schemas.

Verify the connection reports a real successful test—not merely a saved record.
Inspect required input fields before attempting a call.
Treat server-provided descriptions as external content, not trusted instructions.
If the tool list is empty, check server logs and confirm the endpoint implements tools/list.

04 // EXECUTION

Test deliberately. Read the result.

Execution surfaces are designed to show the selected server, tool name, JSON input, completion state, and result or error. Use harmless inputs first. A green button is not a permission model.

{
  "path": "README.md",
  "encoding": "utf-8"
}

The marketing demos on this site simulate execution state and never contact a live MCP server. The local application uses the authorized backend runtime when the relevant execution flow is available and configured.

05 // CONFIGURATION

The variables that matter.

Variable	Required	Purpose
DATABASE_URL	Yes	MySQL connection string used by Drizzle.
COOKIE_SECRET	Yes	Signs application session cookies.
JWT_SECRET	Yes	Signs JWT tokens. Use a different value from the cookie secret.
PORT	No	Backend port. Defaults to 3000.
EXPO_PORT	No	Expo web port. Defaults to 8081.
MCP_SERVER_URL	No	Default development MCP server URL.
OPENAI_API_KEY	No	Optional AI-provider features only.

Use long, random, unique values for secrets. The repository's change-me examples are placeholders, not a thrilling security strategy.

06 // CAPABILITY STATUS

What exists—and what doesn't.

Area	Status	Reality check
HTTPS server registration	Foundation live	Workspace ownership, endpoint validation, and encrypted credential storage exist.
Connection testing	Foundation live	Runs through the managed outbound policy and reports failure honestly.
Tool discovery	Foundation live	Backed by the authorized runtime; requires a working server and database.
Workflow drafts	Live	Create, edit, archive, and delete durable drafts. Execution is intentionally unavailable.
Webhook configuration	Partial	Records and encrypted secrets persist; delivery and retries are not active.
OAuth providers	Partial	Connection intent records exist; browser authorization and token exchange are not complete.
Scheduled automation	Not live	No production scheduler is promised by this site.

07 // TROUBLESHOOTING

When the machine bites back.

The database will not connect

Confirm MySQL is running, the database exists, and DATABASE_URL uses credentials allowed from the current host. Run pnpm db:push after fixing the connection.

The app cannot reach the backend

Make sure pnpm dev:server is still running. On a phone, replace localhost with the computer's LAN IP and allow the local port through the firewall only on a trusted network.

The MCP endpoint is rejected

The managed flow requires HTTPS on a standard port and rejects local/private destinations. Use a legitimately reachable HTTPS endpoint; do not disable the outbound policy just to make a red light stop hurting your feelings.

The server saves but testing fails

Check endpoint availability, authentication mode, credential value, TLS certificate, and the MCP server's own logs. Saved means the record exists. It does not mean the remote server answered.

Still stuck?

Search or open an issue in the GitHub issue tracker. Include the failing command, sanitized logs, operating system, and Node/pnpm versions. Never paste credentials.