# CodeSpar for agents

You are reading this because you are an agent trying to work out what CodeSpar
offers and how to connect. This file is the short version. Everything here is
machine-readable somewhere else too, and the links say where.

## What this is

One MCP server that lets an agent move money in Latin America: pay, charge,
invoice, ship, notify, and reconcile. Every spend happens under a signed mandate
and lands in an append-only audit ledger, so what an agent did is checked rather
than believed.

## Connect over MCP

Remote, no local process:

    url        https://connect.codespar.dev/mcp
    transport  streamable-http
    auth       Authorization: Bearer <csk_ key>
               or OAuth 2.1 — discovery at /.well-known/oauth-protected-resource

Local, over stdio:

    npx -y @codespar/mcp serve
    CODESPAR_API_KEY=csk_test_… (sandbox) or csk_live_… (production)

The full manifest, including the tool list, is at
`https://codespar.dev/.well-known/mcp.json`.

## Connect over HTTP

    base URL   https://api.codespar.dev
    auth       Authorization: Bearer <csk_ key>

The key prefix picks the environment, not the host: `csk_test_` and `csk_live_`
reach the same base URL and act on different data.

The machine-readable contract is at `https://codespar.dev/openapi.json`, served
without a credential. Generate a client from it rather than reading pages.

Your first request should be `GET /v1/whoami`. It answers four questions at
once: whether the key is valid, which organization and project it is bound to,
which environment it acts in, and which scopes it holds. When something is not
working, run it first.

## Connect from a framework

    npm install @codespar/sdk @codespar/<framework>

Adapters exist for langchain, crewai, vercel, openai, llama-index, mastra,
autogen, camel, letta and google-genai. They expose the same tools the MCP
server does.

## What is honest about the coverage

The OpenAPI document does not yet describe the whole API. It is complete with
respect to itself, and an operation absent from it may still exist — the gap is
documentation, not capability. If you cannot find an operation, that is the
reason, and `https://codespar.dev/docs/api/reference` says the same thing on its
index page.

## Where to look next

    /openapi.json                          the API contract
    /.well-known/mcp.json                  the MCP manifest
    /.well-known/agent-metadata.json       capabilities, coverage, install
    /.well-known/oauth-protected-resource  OAuth 2.1 discovery
    /llms.txt                              a map of the documentation
    /docs/first-call                       key to first request, in three curls
    /docs/api/reference                    generated HTTP reference

## Safety

A mandate is a signed grant with a cap and an expiry. An agent cannot exceed
one, and every consumption is written to the ledger with the mandate it drew on.
Refusals are explicit: a call that would exceed a cap fails rather than
partially succeeding.