​

MCP: tools and resources for agents

​

Enable it

cratestack = { package = "cratestack-pg", version = "0.14", features = ["mcp"] }

mcp {
  name = "blog"
  expose = [tools, resources]
}

model Post {
  id Int @id
  authorId String
  title String
  published Boolean

  @@allow("read", published || authorId == auth().id)
  @@mcp(resource: "posts")
}

procedure recentPosts(limit: Int): Post[]
  @allow(auth() != null)
  @mcp(tool: "recent_posts", description: "The newest posts you may read.")

mutation procedure publishPost(id: Int): Post
  @allow(auth() != null && auth().role == "editor")
  @mcp(tool: "publish_post", description: "Publish a draft post. Editors only.")

​

The schema rules

• mcp { } takes expose = [tools], [resources] or both. name is required when resources is exposed, and refused otherwise.
• name is the host of every resource URI (cratestack://blog/...), so it is a DNS label:
  • lowercase letters, digits and -, 1 to 63 characters, not starting or ending with -;
  • it may not have -- as its 3rd and 4th characters (IDNA’s reserved form, as in xn--);
  • it must contain a letter, so 127 is refused.
• @mcp(tool: "name") exposes a procedure. A bare @mcp(tool) uses the procedure’s own name. description: is optional. The procedure must have an @allow; @deny alone is not enough.
• @@mcp(resource: "segment") exposes a model. It must have a read allow, @@allow("read", ...) or @@allow("all", ...). An optional max_page_size: (1 to 200) lowers the page-size cap.

​

Serve it over stdio

let ctx = cratestack::SystemContext::for_service("support-agent").into_context();
cratestack::mcp::StdioServer::new(cratestack_schema::mcp::tools(db, registry, resolvers), ctx)?
    .serve()
    .await?;

​

Serve it over Streamable HTTP

let resource = ProtectedResource::new("https://api.example.com/mcp", ["https://auth.example.com"]);
let mcp = StreamableHttpServer::builder(tools, auth_provider, ["https://app.example.com"], resource)
    .build()?;
let app = Router::new()
    .nest_service("/mcp", mcp.service())
    .merge(mcp.metadata_router()); // RFC 9728 metadata, at the root

​

A provider that does not use bearer tokens

use cratestack::mcp::CredentialPresence;
use cratestack::axum::http::HeaderName;

let mcp = StreamableHttpServer::builder(tools, auth_provider, origins, resource)
    .with_credential_presence(
        CredentialPresence::provider_decides().with_credential_headers([
            HeaderName::from_static("x-attestation"),
            HeaderName::from_static("x-signature"),
        ]),
    )
    .build()?;

• CredentialPresence::bearer() is the default, unchanged.
• CredentialPresence::provider_decides() sends every request to your provider.
• CredentialPresence::when(|parts| ...) tests the request head (method, URI, headers and extensions, never the body).
• with_credential_headers names the headers that carry the credential. They are removed before the MCP server sees the request, as Authorization is, and their values are cut out of your provider’s logged error detail.

​

What a tool call goes through

1. The tool name is looked up. An unknown name is JSON-RPC -32602.
2. The arguments are decoded into the procedure’s Args. A failure is an isError result that names the field.
3. If you passed an OpExecutor with with_executor, L3 admission runs: rate limiting, then idempotency. An idempotency key travels in _meta["dev.cratestack/idempotencyKey"]; without one, nothing is reserved. A failing rate-limit store follows the StoreErrorPolicy you pass to with_store_error_policy, the same type RateLimitLayer uses on HTTP. The budget is per caller and per transport: a caller’s MCP calls and its REST calls are counted separately. (since 0.14.0) The MCP key holds a SHA-256 of the caller’s id, not the id itself. After upgrading from 0.13.0 with a shared store, MCP idempotency records written by 0.13.0 no longer replay and MCP rate-limit buckets start fresh.
4. The procedure’s generated invoke_with_db runs @allow / @deny and any @authorize(...), then your implementation. Its ORM calls carry @@allow in their SQL. (Since 0.14.1.) For a procedure that declares @isolation, all of this runs in one transaction at the declared level and is retried on a serialization failure or deadlock, as on REST and RPC. When the retries run out, the result is an isError result with code TRANSACTION_ABORTED, and the idempotency reservation is released rather than recorded, so the same key runs the call again. In 0.14.0 and earlier, @isolation has no effect on MCP either.

​

Resources

• cratestack://blog/posts/{id}: one record, shaped exactly like REST’s GET /posts/{id}. @server_only fields are absent and @computed fields are resolved.
• cratestack://blog/posts{?limit,cursor}: a page, {"items": [...], "nextCursor": "..."}, in primary-key order. limit defaults to 50 and is clamped, not refused, at 200 or at the model’s max_page_size. Pass nextCursor back as cursor.

​

Connecting a client

​

Not in v1

• CRUD-derived tools. Only procedures are tools, and models are read-only resources.
• Filtering tools/list by the caller’s authorization. Every caller sees the whole table, and each call is still policy-checked.
• MCP on the embedded role (cratestack-sqlite).
• A generic OAuth AuthProvider. You bring your own, and it must check the audience.