Skip to content

Add mesh token to on config #2125

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
vibegui wants to merge 7 commits into from
Closed

Add mesh token to on config #2125

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
c3ac71f
Add mesh token to on config
vibegui Jan 1, 2026
f79d6b2
Enhance documentation and implement STDIO connection support
vibegui Jan 2, 2026
fae8140
Refactor JWT token issuance to use options object for expiration
vibegui Jan 2, 2026
753fe57
fix(stdio): persist state across hot reload for stable STDIO connections
vibegui Jan 4, 2026
5ed918f
feat(event-bus): add ACK tool and improve worker reliability
vibegui Jan 4, 2026
9a19176
fix(event-bus): process events published during batch, improve HMR cl…
vibegui Jan 4, 2026
5f13dbc
Improve layout and env vars
vibegui Dec 30, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 23 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,11 +49,34 @@ Bun is the test runner throughout. Co-locate test files next to source as `*.tes
## Authentication & Authorization
Uses Better Auth for authentication (OAuth 2.1 + SSO + API keys). Authorization uses custom AccessControl layer with organization/project-level RBAC. Auth configuration is in `apps/mesh/auth-config.json` (example: `auth-config.example.json`).

## Documentation Requirements

**IMPORTANT**: Documentation must be updated alongside code changes. Before committing:

1. **Check for relevant docs** in `apps/docs/client/src/content/` (EN + PT-BR)
2. **Update affected docs** when changing:
- API behavior or endpoints
- Configuration options
- Authentication/authorization flows
- Connection types or proxy behavior
- New features or removed functionality
3. **Update README.md** for significant features
4. **Review docs diff** before committing to ensure accuracy

Documentation locations:
- `apps/docs/client/src/content/en/` - English docs
- `apps/docs/client/src/content/pt-br/` - Portuguese docs
- `README.md` - Project overview and quick start
- `packages/*/README.md` - Package-specific docs

Run `bun run docs:dev` to preview documentation changes locally.

## Commit & Pull Request Guidelines
Follow Conventional Commit-style history: `type(scope): message`, optionally wrapping the type in brackets for chores (e.g., `[chore]: update deps`). Reference issues with `(#1234)` when applicable. PRs should include:
- Succinct summary of changes
- Testing notes and affected areas
- Screenshots for UI changes
- **Documentation updates** for any behavior changes
- Confirm formatting (`bun run fmt`) and linting (`bun run lint`) pass
- Run tests (`bun test`) before requesting review
- Flag follow-up work with TODOs linked to issues
17 changes: 17 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -96,6 +96,23 @@ Gateways are configurable and extensible. You can add new strategies and also cu

---

## STDIO Connections (Local MCPs)

Run npx packages or custom scripts as MCP servers. Mesh passes credentials via environment variables:

```bash
# Mesh spawns your MCP with these env vars:
MESH_TOKEN=<jwt> # Infinite-expiry JWT for mesh API calls
MESH_URL=<url> # Mesh instance URL
MESH_STATE=<json> # Binding values as JSON
```

Your MCP just reads `process.env.MESH_TOKEN` — no special configuration tools needed. This mirrors how HTTP connections receive `x-mesh-token` headers.

→ See [Building STDIO MCPs](https://docs.deco.page/en/mcp-mesh/mcp-servers) for examples in [decocms/mcps](https://github.com/decocms/mcps).

---

## Define Tools

Tools are first-class citizens. Type-safe, audited, observable, and callable via MCP.
Expand Down
64 changes: 63 additions & 1 deletion apps/docs/client/src/content/en/mcp-mesh/mcp-servers.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,69 @@ import Callout from "../../../components/ui/Callout.astro";

## What is a connection?

An **MCP Server** in the Mesh is a configured upstream MCP endpoint (typically HTTP). The Mesh stores its configuration and (optionally) credentials, and can then proxy MCP requests to it.
An **MCP Server** in the Mesh is a configured upstream MCP endpoint. The Mesh stores its configuration and (optionally) credentials, and can then proxy MCP requests to it.

## Connection Types

The Mesh supports two types of connections:

### HTTP Connections

HTTP connections are the most common type. They connect to remote MCP servers via HTTP/SSE endpoints.

- **Use cases**: Cloud-hosted MCP servers, SaaS integrations, production deployments
- **Token handling**: Short-lived tokens (5 minutes) issued per request

### STDIO Connections (Local Commands)

STDIO connections spawn a local process (like `npx` or custom scripts) and communicate via stdin/stdout.

- **Use cases**: Local tools, npx packages, development, private MCPs
- **Token handling**: Infinite-expiry tokens persisted locally by the MCP server

<Callout type="tip">
STDIO connections are perfect for running npm packages as MCP servers. Example: `npx @decocms/local-fs` runs a file system MCP locally.
</Callout>

## STDIO Credentials via Environment Variables

When mesh spawns an STDIO MCP process, it passes credentials as environment variables:

| Variable | Description |
|----------|-------------|
| `MESH_TOKEN` | JWT token for authenticating with Mesh API (infinite expiry) |
| `MESH_URL` | Base URL of the Mesh instance |
| `MESH_STATE` | JSON-encoded state with binding values |

This is analogous to how HTTP connections receive `x-mesh-token` headers.

<Callout type="tip">
**No special tools needed!** Just read `process.env.MESH_TOKEN` on startup. No need to implement `ON_MCP_CONFIGURATION` or any configuration protocol.
</Callout>

### Example (Node.js/Bun)

```typescript
// Read mesh credentials from env
const meshToken = process.env.MESH_TOKEN;
const meshUrl = process.env.MESH_URL;
const state = process.env.MESH_STATE ? JSON.parse(process.env.MESH_STATE) : {};

// Use token for mesh API calls
const response = await fetch(`${meshUrl}/mcp/${connectionId}`, {
headers: { Authorization: `Bearer ${meshToken}` },
// ...
});
```

## Building STDIO-Compatible MCPs

See examples in the [decocms/mcps](https://github.com/decocms/mcps) repository:

- `template-minimal/` - Minimal MCP without view
- `template-with-view/` - MCP with web interface
- `local-fs/` - File system MCP (runs via npx)
- `perplexity/`, `openrouter/` - Production MCPs

## In the UI

Expand Down
68 changes: 65 additions & 3 deletions apps/docs/client/src/content/pt-br/mcp-mesh/mcp-servers.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,24 +1,86 @@
---
title: MCP Servers
description: Conexões com MCP servers upstream (HTTP) que o Mesh faz proxy e observa
description: Conexões com MCP servers upstream que o Mesh faz proxy e observa
icon: Server
---

import Callout from "../../../components/ui/Callout.astro";

## O que é um MCP Server (no Mesh)?

No Mesh, um **MCP Server** é uma **connection** para um MCP upstream (normalmente um endpoint MCP via HTTP).
No Mesh, um **MCP Server** é uma **connection** para um MCP upstream.

Cada connection guarda:

- **URL do MCP**
- **URL do MCP** (para HTTP) ou **comando** (para STDIO)
- **credenciais/config** (quando necessário, armazenadas no vault)
- metadados para operação (nome, status, etc.)

## Tipos de Conexão

### Conexões HTTP

Conexões HTTP conectam a servidores MCP remotos via endpoints HTTP/SSE.

- **Casos de uso**: MCPs em nuvem, integrações SaaS, produção
- **Tokens**: JWT com expiração curta (5 minutos)

### Conexões STDIO (Comandos Locais)

Conexões STDIO iniciam um processo local (como `npx` ou scripts) e comunicam via stdin/stdout.

- **Casos de uso**: Ferramentas locais, pacotes npx, desenvolvimento
- **Tokens**: JWT sem expiração, persistido localmente

<Callout type="tip">
Conexões STDIO são perfeitas para rodar pacotes npm como MCPs. Exemplo: `npx @decocms/local-fs` roda um MCP de sistema de arquivos localmente.
</Callout>

## Credenciais STDIO via Variáveis de Ambiente

Quando o mesh inicia um processo MCP STDIO, ele passa credenciais como variáveis de ambiente:

| Variável | Descrição |
|----------|-----------|
| `MESH_TOKEN` | Token JWT para autenticação com a API do Mesh (sem expiração) |
| `MESH_URL` | URL base da instância Mesh |
| `MESH_STATE` | Estado com valores de bindings em JSON |

Isso é análogo a como conexões HTTP recebem headers `x-mesh-token`.

<Callout type="tip">
**Nenhuma ferramenta especial necessária!** Apenas leia `process.env.MESH_TOKEN` na inicialização. Não precisa implementar `ON_MCP_CONFIGURATION` ou qualquer protocolo de configuração.
</Callout>

### Exemplo (Node.js/Bun)

```typescript
// Ler credenciais mesh das env vars
const meshToken = process.env.MESH_TOKEN;
const meshUrl = process.env.MESH_URL;
const state = process.env.MESH_STATE ? JSON.parse(process.env.MESH_STATE) : {};

// Usar token para chamadas à API mesh
const response = await fetch(`${meshUrl}/mcp/${connectionId}`, {
Copy link
Contributor

@cubic-dev-ai cubic-dev-ai bot Jan 2, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: The example uses connectionId which is never defined. Consider either defining it (e.g., from state or as a placeholder) or replacing it with a string literal to make the example self-contained.

Prompt for AI agents 
Check if this issue is valid — if so, understand the root cause and fix it. At apps/docs/client/src/content/pt-br/mcp-mesh/mcp-servers.mdx, line 64:

<comment>The example uses `connectionId` which is never defined. Consider either defining it (e.g., from `state` or as a placeholder) or replacing it with a string literal to make the example self-contained.</comment>

<file context>
@@ -36,16 +36,36 @@ Conexões STDIO iniciam um processo local (como `npx` ou scripts) e comunicam vi
+const state = process.env.MESH_STATE ? JSON.parse(process.env.MESH_STATE) : {};
+
+// Usar token para chamadas à API mesh
+const response = await fetch(`${meshUrl}/mcp/${connectionId}`, {
+  headers: { Authorization: `Bearer ${meshToken}` },
+  // ...
</file context>

✅ Addressed in f79d6b2

headers: { Authorization: `Bearer ${meshToken}` },
// ...
});
```

## Quando usar vs Gateway

- Use **connection** para isolar e depurar um upstream específico.
- Use **gateway** para expor um surface agregado/curado para os clients.

## Construindo MCPs STDIO

Veja exemplos no repositório [decocms/mcps](https://github.com/decocms/mcps):

- `template-minimal/` - MCP mínimo sem view
- `template-with-view/` - MCP com interface web
- `local-fs/` - MCP de sistema de arquivos (roda via npx)
- `perplexity/`, `openrouter/` - MCPs em produção

## Boas práticas

- Mantenha URLs e credenciais por ambiente (dev/staging/prod).
Expand Down
Loading