io.github.sapiom/mcp
Sapiom MCP server — authentication, verification, and API tools
Open source Open in the app JSON README (API)
About
Sapiom MCP server — authentication, verification, and API tools
Details
- Kind
- MCP servers
- Topic
- Security & identity
- Publisher
- sapiom
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.8.0
- Stars
- 19
- Forks
- 30
- Open pull requests
- 89
- Last push
- 2026-09-05T13:23:26Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 04:01:21
- Updated
- 2026-08-29 04:01:21
- Origin id
io.github.sapiom/mcp
README
# Sapiom SDK
[](https://opensource.org/licenses/MIT)
[](https://www.typescriptlang.org/)
> ⚠️ **Beta Status:** Currently in v0.x (beta). API may change before v1.0.0.
> Production-ready and actively maintained.
TypeScript SDK for **building, running, and operating AI agents on Sapiom**.
Author agents as typed step graphs, call Sapiom paid tools (sandboxes, git
repos, coding models, search, file storage, …) directly from your code, and ship
them to the Sapiom engine from the CLI, your coding agent's MCP, or the
**Sapiom Studio** desktop app.
## 📦 Packages
This is a monorepo of focused packages. Install only what you need.
### Build & run agents
| Package | Version | Description |
| --------------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| [@sapiom/agent](./packages/agent) | [](https://www.npmjs.com/package/@sapiom/agent) | The authoring contract: `defineAgent`, `defineStep`, directives (`goto`/`terminate`), and types |
| [@sapiom/tools](./packages/tools) | [](https://www.npmjs.com/package/@sapiom/tools) | Typed client for Sapiom capabilities — the same tools your agents call, callable from your code |
| [@sapiom/cli](./packages/cli) | [](https://www.npmjs.com/package/@sapiom/cli) | Command line: scaffold, validate, deploy, and schedule agents |
| [@sapiom/mcp](./packages/mcp) | [](https://www.npmjs.com/package/@sapiom/mcp) | Local developer MCP server (`sapiom-dev`) — build & operate agents from your coding agent |
### Agent Studio
Agent Studio runs your coding agent (Claude Code or Codex) in a
Sapiom-configured environment: MCP pre-wired, agent projects tracked, one-click
deploy/run, and a live canvas for previews.
| Package | Version | Description |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| [@sapiom/agent-studio](./packages/agent-studio) | [](https://www.npmjs.com/package/@sapiom/agent-studio) | Agent Studio launcher — `npx @sapiom/agent-studio@latest` |
| [@sapiom/harness](./packages/harness) | [](https://www.npmjs.com/package/@sapiom/harness) | The Agent Studio implementation — a CLI-launched local web app |
| [@sapiom/harness-desktop](./packages/harness-desktop) | [](https://github.com/sapiom/sapiom-js/releases) | **Sapiom Studio** desktop app (Electron) — ships as signed installers, not to npm |
### Runtime internals
Lower-level packages that power the stack above. Most users never import these
directly, but they're published for advanced/host integrations.
| Package | Version | Description |
| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| [@sapiom/agent-core](./packages/agent-core) | [](https://www.npmjs.com/package/@sapiom/agent-core) | Pure, stateless functions for scaffolding, validating, and operating agents — shared by the CLI and MCP |
| [@sapiom/agent-runtime](./packages/agent-runtime) | [](https://www.npmjs.com/package/@sapiom/agent-runtime) | Host-agnostic graph-walker runtime — one runtime, two hosts (server engine + local runner) |
## 🚀 Quick Start
**New to Sapiom?** The fastest path is the CLI or the developer MCP — both
scaffold a working agent for you. See the [examples folder](./examples) for
complete, runnable projects.
### Scaffold an agent with the CLI
```bash
npx @sapiom/cli agents init my-app # scaffold a project
cd my-app
npx @sapiom/cli agents check # validate locally (bundle, manifest, graph)
npx @sapiom/cli agents deploy # build and ship
```
### Build with your coding agent in Agent Studio
One command checks your environment, signs you in, and opens Agent Studio with
your coding agent running in an embedded terminal:
```bash
npx @sapiom/agent-studio@latest [dir]
```
Prefer a native app? **Sapiom Studio** is the one-click desktop host for the
same experience — download installers (macOS, Windows, Linux) from
[GitHub Releases](https://github.com/sapiom/sapiom-js/releases).
### Author an agent
An agent is a typed graph of steps. Each step does work and returns a directive
telling the runtime where to go next.
```typescript
import { defineAgent, defineStep, goto, terminate } from "@sapiom/agent";
const start = defineStep({
name: "start",
next: ["finish"],
async run(input, ctx) {
return goto("finish", { greeting: `hello ${input.name}` });
},
});
const finish = defineStep({
name: "finish",
next: [],
terminal: true,
async run(input) {
return terminate({ done: true, ...input });
},
});
export const hello = defineAgent({
name: "hello",
entry: "start",
steps: { start, finish },
});
```
### Call Sapiom capabilities from your code
`@sapiom/tools` exposes the same capabilities your agents call as tools, typed
and authenticated to your tenant.
```typescript
import { createClient } from "@sapiom/tools";
const sapiom = createClient({ apiKey: process.env.SAPIOM_API_KEY });
// Create a repo, have a coding model build into it, then publish.
const repo = await sapiom.repositories.create("landing-page");
const run = await sapiom.models.coding.run({
task: "Build a one-page marketing site in index.html.",
gitRepository: repo,
});
if (run.result?.success) {
const { sha } = await repo.pushFromSandbox(run.sandbox, {
message: "build: landing",
});
console.log("published", sha);
}
```
### Build agents from your coding agent (MCP)
Add the local developer MCP so your coding agent can scaffold, test, deploy, and
inspect Sapiom agents. In Claude Code:
```sh
claude mcp add sapiom-dev -- npx -y @sapiom/mcp
```
> `@sapiom/mcp` is the **local developer** surface (`sapiom_dev_*`). It is
> distinct from the remote Sapiom capability MCP that services paid tool calls —
> see [docs/mcp-servers.md](./docs/mcp-servers.md) for which to use when.
## 📚 Documentation
- **[Examples](./examples/README.md)** — runnable example projects
- **[The two Sapiom MCP servers](./docs/mcp-servers.md)** — local dev vs. remote capabilities
- **[@sapiom/agent](./packages/agent/README.md)** — authoring contract
- **[@sapiom/tools](./packages/tools/README.md)** — capability client
- **[@sapiom/cli](./packages/cli/README.md)** — command line
- **[@sapiom/mcp](./packages/mcp/README.md)** — developer MCP
- **[Agent Studio](./packages/harness/README.md)** — local app for building with your coding agent
## 🏗️ Package Architecture
```
@sapiom/agent Authoring contract (defineAgent, directives, types)
↑
├── @sapiom/agent-runtime Host-agnostic graph-walker runtime
└── @sapiom/agent-core Scaffold / validate / operate (pure functions)
↑
├── @sapiom/cli Command line
└── @sapiom/mcp Local developer MCP (sapiom-dev)
@sapiom/tools Typed capability client (sandboxes, repos, models, …)
@sapiom/harness Agent Studio (local web app; launched via @sapiom/agent-studio)
↑
└── @sapiom/harness-desktop Sapiom Studio desktop app (Electron host, ships as installers)
```
## 🛠️ Development
This is a pnpm workspace monorepo.
```bash
# Install dependencies
pnpm install
# Build all packages
pnpm build
# Run tests
pnpm test
# Lint and format
pnpm lint
pnpm format
```
### Package Scripts
```bash
# Build / test a specific package
pnpm --filter @sapiom/agent build
pnpm --filter @sapiom/tools test
# Watch mode
pnpm --filter @sapiom/agent dev
```
### Publishing
We use [Changesets](https://github.com/changesets/changesets) for version management:
```bash
pnpm changeset # create a changeset
pnpm version-packages # apply version bumps
pnpm release # build and publish to npm
```
## 🤝 Contributing
Contributions welcome! Please read our [Contributing Guide](./CONTRIBUTING.md)
first — it explains which changes can go straight to a pull request (focused
bug fixes, documentation corrections, single-template additions) and which need
a maintainer-agreed [issue](https://github.com/sapiom/sapiom-js/issues) before
you invest in them (new features, public API changes, new dependencies,
cross-package work).
In short:
1. Fork the repository and branch from the latest `main`
2. Keep the change focused on one problem, with tests for changed behavior
3. Run the root checks (`pnpm build`, `pnpm typecheck`, `pnpm lint`, `pnpm test`)
4. Add a [changeset](./CONTRIBUTING.md#changesets) when a published package's behavior or API changes
5. Open a pull request and complete every applicable section of the template
AI-assisted contributions are welcome but must be disclosed, reviewed, and
validated by the contributor. For suspected security vulnerabilities, follow
the [Security Policy](./SECURITY.md) instead of opening a public issue.
## 📄 License
MIT © [Sapiom](LICENSE)
## 🔗 Links
- [Website](https://sapiom.ai)
- [Documentation](https://docs.sapiom.ai)
- [NPM Organization](https://www.npmjs.com/org/sapiom)
- [GitHub Issues](https://github.com/sapiom/sapiom-js/issues)