OneC MCP

A Go service that acts as a gateway between an LLM/MCP client and 1C ERP via HTTP.

Features

• Reference resolution - search customers, warehouses, products, sales channels, cash desks, cost articles, and operation types by free-text query, with hierarchical group support
• Sales reporting - sales, top products, and per-customer summaries with filters, grouping, sorting, and (scoped) cost/profit/margin measures
• Stock reporting - product stock balances as of a date
• Money reporting - cash-on-hand balances and cash flow turnovers
• Settlements & purchases - receivables/payables balances (ДЗ/КЗ, expanded by sign) and goods-purchase turnover; together with stock they cover the full Cash Conversion Cycle (DIO/DSO/DPO)
• MCP protocol support - JSON-RPC 2.0 endpoint for LLM integration
• OAuth 2.0 - per-user keys, scope-based tool access, and audit logging
• Multi-database - several 1C databases behind one gateway, each under its own path slug and its own OAuth authorization server
• Admin UI - databases are stored in SQLite and managed at /admin, no restart and no config edit required

Requirements

• Go 1.23+
• 1C HTTP service (or mock server for development)

Quick Start

# Run the server
go run ./cmd/server

# Test health endpoint
curl http://localhost:8088/health

# Add a 1C database at http://localhost:8088/admin, then use its slug:
curl -X POST http://localhost:8088/tenant1/mcp \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <oauth-access-token>' \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

A fresh database has no tenants, so the gateway starts serving nothing but
/health and /admin. That is expected — add the first 1C database in the
admin UI.

Configuration

Copy and edit the config file:

cp configs/config.yml configs/config.local.yml

The config holds only what the gateway needs in order to boot and open /admin.
1C databases are not in the config — they live in SQLite and are managed
through the admin UI.

Managing databases

Everything about a 1C database — its slug, 1C address and Basic credentials,
timeouts, tokens, scope overrides — is edited at /admin, behind Basic auth with
the credentials from the config. Changes take effect immediately: the router
resolves slugs through a registry that is rebuilt on every save, so no restart is
needed.

Each database gets a slug, and the slug is the first path segment: /tenant1/mcp,
/tenant1/oauth/*, /tenant1/resolve/*. Slugs must match [a-z0-9-] and cannot
be health, admin, mcp, oauth, or .well-known. A slug cannot be renamed
after creation — it is baked into connector URLs, the OAuth issuer, and the
audience of every token already issued.

Authentication. OAuth 2.0 is the primary auth for the /{slug}/mcp
endpoint: LLM clients register dynamically, obtain a per-user token, and the
token's granted scopes drive tool access. Every database runs its own
authorization server — issuer is <public_url>/<slug> and the token audience is
<public_url>/<slug>/mcp — so a token minted for one database is rejected on
every other. A database's static MCP token is only a fallback for local
development and curl tests when oauth.enabled = false; a database with
neither OAuth nor a static token gets no MCP route at all, rather than an
unauthenticated one. REST endpoints (/{slug}/resolve/*, /{slug}/reports/*)
are a separate server-side integration surface guarded by the database's own API
token, independent of OAuth. See the
OAuth Setup & Admin Guide.

Documentation

Project Structure

├── cmd/server/          # Application entry point
├── configs/             # Configuration files
├── docs/                # Documentation
├── internal/
│   ├── admin/           # /admin web UI for managing 1C databases
│   ├── api/             # HTTP handlers, router, tenant registry
│   ├── config/          # Configuration loader
│   ├── mcp/             # MCP JSON-RPC handler
│   ├── oauth/           # OAuth 2.0 server, scopes, audit
│   ├── onec/            # 1C HTTP client
│   ├── store/           # Shared SQLite handle
│   └── tenant/          # 1C database records and their storage
├── go.mod
└── go.sum

Endpoints

{slug} is the slug of a database created in the admin UI. Only /health,
/admin/* and the canonical .well-known/* paths live at the root.

Discovery metadata is also served under /{slug}/.well-known/... for clients
that look for it beneath the resource prefix instead of the canonical
path-insertion form.

REST endpoints are mounted only for databases that set an API token; the OAuth
and discovery endpoints only when oauth.enabled is true. A disabled database
serves no routes at all.

MCP Tools

Scopes

Each tool requires a scope; tools/list is filtered to the caller's granted
scopes and tools/call is rejected without the matching scope. The
mcp:report:cost scope works on three levels at once: it unlocks the cost,
profit, and margin measures in sales_report and customer_summary; it
gates the production tools (resolve_material, product_specification,
specification_*, production_*); and it widens what the shared tools return —
resolve_warehouse starts listing production warehouses, stock_balance and
availability_report start covering materials on them. Scopes are enforced
again on the 1C side via the X-MCP-Scopes header (defense in depth). See the
OAuth Setup & Admin Guide for issuing per-user keys.