Server API Overview - Toolshed

The Toolshed API server is built with Hono and uses Better Auth for authentication. All endpoints are under the /api base path.

Authentication

Routes are protected by one of two mechanisms:

Better Auth session cookie — set automatically by the web app after login
Bearer token — Authorization: Bearer <TOOLSHED_API_SECRET> for CLI and programmatic access

Unauthenticated routes:

GET /api/health
GET|POST /api/auth/* (handled by Better Auth)
ALL /api/mcp/:token (authenticates via the MCP token in the URL — see MCP Server Overview)

Route groups

Group	Path prefix	Description	Status
Auth	`/api/auth`	Better Auth (login, OAuth social + genericOAuth, sessions)	Implemented
Connections	`/api/connections`	Tool connections with encrypted secrets, MCP endpoints	Implemented
Connectors	`/api/connectors`	Connector availability registry (which providers have creds)	Implemented
Tokens	`/api/tokens`	OAuth token vending + three-source `resolveToken()`	Implemented
Remote MCP	`/api/mcp/:token`	HTTP MCP transport (`StreamableHTTPTransport` from `@hono/mcp`) — see MCP Overview	Implemented
Registry	`/api/registry`	Tool catalog, source registration, search	Implemented
Policy	`/api/policy`	Role management and access resolution	Stub
Audit	`/api/audit`	Audit trail for tool invocations	Stub
Elicitation	`/api/elicitation`	Pending approval storage and resolution	Stub

Health check

GET /api/health
→ { "ok": true }

Local development

# Copy env template and fill in credentials
cp apps/server/.env.example apps/server/.env.local

# Start the dev server (loads .env.local automatically)
pnpm --filter @toolshed/server dev

The server runs at http://localhost:3000 by default.