sac-mcp

MCP Server for Stellar Smart Contract

This server implements the Model Context Protocol (MCP) and acts as a tool provider for a Soroban smart contract deployed on the Stellar blockchain.

It exposes a standardized MCP interface that allows agents (such as AI models, orchestration frameworks, or automation tools) to discover and invoke the smart contract's available functions safely and consistently.

This server was auto-generated using the Soroban CLI and is optimized for plug-and-play integration into any MCP-compatible environment.

---

📝 Next steps

1. Install dependencies and build the project:
``bash
cd sac-mcp
npm install
npm run build
`

2. Add the following configuration to your MCP config file (e.g., in claude_desktop_config.json, mcp.config.json, etc.):
`json
"sac_mcp": {
"command": "node",
"args": [
"sac-mcp/build/index.js"
],
"env": {
"NETWORK": "testnet",
"NETWORK_PASSPHRASE": "Test SDF Network ; September 2015",
"RPC_URL": "https://soroban-testnet.stellar.org",
"CONTRACT_ID": "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC"
}
}
`
This allows MCP runtimes to run your tool seamlessly.

🧠 What This Server Does
Implements the MCP spec to serve Soroban contract methods as tools.

Each method is described via a JSON schema (input/output), allowing agents to introspect and invoke them programmatically.

All logic is executed via Stellar's Soroban smart contract runtime.

⚠️ There are no REST endpoints exposed. Tool interaction happens via MCP-compatible interfaces.

🧪 Exposed Contract Tools
The following contract methods are exposed as MCP tools:

- allowance: Returns the allowance for spender to transfer from from. The amount returned is the amount that spender is allowed to transfer out of from's balance. When the spender transfers amounts, the allowance will be reduced by the amount transferred. # Arguments from - The address holding the balance of tokens to be drawn from. spender - The address spending the tokens held by from.
- authorized: Returns true if id is authorized to use its balance. # Arguments * id - The address for which token authorization is being checked.
- approve: Set the allowance by amount for spender to transfer/burn from from. The amount set is the amount that spender is approved to transfer out of from's balance. The spender will be allowed to transfer amounts, and when an amount is transferred the allowance will be reduced by the amount transferred. # Arguments from - The address holding the balance of tokens to be drawn from. spender - The address being authorized to spend the tokens held by from. amount - The tokens to be made available to spender. expiration_ledger - The ledger number where this allowance expires. Cannot be less than the current ledger number unless the amount is being set to 0. An expired entry (where expiration_ledger < the current ledger number) should be treated as a 0 amount allowance. # Events Emits an event with topics ["approve", from: Address, spender: Address], data = [amount: i128, expiration_ledger: u32]
- balance: Returns the balance of id. # Arguments * id - The address for which a balance is being queried. If the address has no existing balance, returns 0.
- burn: Burn amount from from. Reduces from's balance by the amount, without transferring the balance to another holder's balance. # Arguments from - The address holding the balance of tokens which will be burned from. amount - The amount of tokens to be burned. # Events Emits an event with topics ["burn", from: Address], data = amount: i128
- burn_from: Burn amount from from, consuming the allowance of spender. Reduces from's balance by the amount, without transferring the balance to another holder's balance. The spender will be allowed to burn the amount from from's balance, if the amount is less than or equal to the allowance that the spender has on the from's balance. The spender's allowance on from's balance will be reduced by the amount. # Arguments spender - The address authorizing the burn, and having its allowance consumed during the burn. from - The address holding the balance of tokens which will be burned from. * amount - The amount of tokens to be burned. # Events Emits an event with topics ["burn", from: Address], data = amount: i128
- clawback: Clawback amount from from account. amount is burned in the clawback process. # Arguments from - The address holding the balance from which the clawback will take tokens. amount - The amount of tokens to be clawed back. # Events Emits an event with topics ["clawback", admin: Address, to: Address], data = amount: i128
- decimals: Returns the number of decimals used to represent amounts of this token. # Panics If the contract has not yet been initialized.
- mint: Mints amount to to. # Arguments to - The address which will receive the minted tokens. amount - The amount of tokens to be minted. # Events Emits an event with topics ["mint", admin: Address, to: Address], data = amount: i128
- name: Returns the name for this token. # Panics If the contract has not yet been initialized.
- set_admin: Sets the administrator to the specified address new_admin. # Arguments * new_admin - The address which will henceforth be the administrator of this token contract. # Events Emits an event with topics ["set_admin", admin: Address], data = [new_admin: Address]
- admin: Returns the admin of the contract. # Panics If the admin is not set.
- set_authorized: Sets whether the account is authorized to use its balance. If authorized is true, id should be able to use its balance. # Arguments id - The address being (de-)authorized. authorize - Whether or not id can use its balance. # Events Emits an event with topics ["set_authorized", id: Address], data = [authorize: bool]
- symbol: Returns the symbol for this token. # Panics If the contract has not yet been initialized.
- transfer: Transfer amount from from to to. # Arguments from - The address holding the balance of tokens which will be withdrawn from. to - The address which will receive the transferred tokens. * amount - The amount of tokens to be transferred. # Events Emits an event with topics ["transfer", from: Address, to: Address], data = amount: i128
- transfer_from: Transfer amount from from to to, consuming the allowance that spender has on from's balance. Authorized by spender (spender.require_auth()). The spender will be allowed to transfer the amount from from's balance if the amount is less than or equal to the allowance that the spender has on the from's balance. The spender's allowance on from's balance will be reduced by the amount. # Arguments spender - The address authorizing the transfer, and having its allowance consumed during the transfer. from - The address holding the balance of tokens which will be withdrawn from. to - The address which will receive the transferred tokens. amount - The amount of tokens to be transferred. # Events Emits an event with topics ["transfer", from: Address, to: Address], data = amount: i128`

Each tool includes parameter validation, metadata, and underlying Soroban invocation logic.

📘 About Model Context Protocol (MCP)
MCP enables agents to discover and use tools through a structured protocol — no hardcoded APIs, just standardized tool definitions and execution environments.

Learn more at modelcontextprotocol.io.

This is an auto-generated server. If you need to modify the contract interface, it's recommended to regenerate the server using the Stellar CLI rather than modifying the generated code directly.