Architecture - Toolshed

Monorepo structure

toolshed/
  apps/
    cli/          CLI tool (login, run, serve)
    server/       API backend (Hono + Vercel + Neon PostgreSQL)
    web/          Static landing page
  packages/
    kernel/       Runtime abstraction (local, Vercel, sandboxed JS)
    mcp-host/     MCP server hosting layer
    policy/       Authorization and consent engine
    sdk/          Plugin and tool definition SDK
    shared/       Shared types and Zod schemas
    sources/      Data source adapters (OpenAPI, MCP, GraphQL, plugins)
  plugins/
    github/       GitHub API integration
    google-workspace/  Gmail, Drive, Calendar
    linear/       Linear issue tracking
    slack/        Slack messaging

Package dependency graph

cli ────→ kernel ────→ policy ────→ shared
  │         │
  ├──────→ mcp-host ──→ kernel
  │
  ├──────→ policy
  └──────→ shared

server ──→ sdk ────────→ shared
  │         │
  ├──────→ sources ────→ sdk
  │                       │
  ├──────→ policy         └──→ shared
  └──────→ shared

plugins (github, linear, google-workspace, slack)
  ├──────→ sdk ──────────→ shared
  └──────→ shared

Data flow

The typical request flow when an agent executes a tool:

MCP Client (Claude, Cursor, etc.)
  │
  │  MCP protocol (stdio)
  ▼
MCP Host (mcp-host)
  │  creates McpServer with 4 tools
  ▼
Runtime (kernel)
  │  executes TypeScript in sandbox
  │  provides tools.* proxy namespace
  ▼
Tool Proxy (kernel/proxy)
  │  translates tools.github.issues.list({...})
  │  into invoke("github.issues.list", args)
  ▼
Elicitation Engine (kernel)
  │  if destructive: pause, wait for approval
  ▼
Plugin Handler / Source Adapter
  │  calls external API (GitHub, Slack, etc.)
  ▼
External Service

Server architecture

The API server is built with Hono and deployed to Vercel. It exposes six route groups under /api:

Route group	Purpose
`/api/auth`	OAuth2 login, callback, token storage
`/api/tokens`	Vend short-lived access tokens for plugins
`/api/registry`	Tool catalog, source registration, search
`/api/policy`	Role management and access resolution
`/api/audit`	Audit trail for tool invocations
`/api/elicitation`	Pending approval storage and resolution

All routes except health check and OAuth flow endpoints require a Bearer token in the Authorization header.

Runtime backends

Runtime	Isolation	Use case
`RuntimeLocal`	None (in-process `new Function()`)	Local development with trusted scripts
`RuntimeVercel`	Firecracker microVM via Vercel Sandbox	Production with untrusted agent-generated code