diff --git a/README.md b/README.md
index d6b595b..c305c46 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,79 @@
 # cs-mic-mcp
 
-An MCP server  providing deterministic to LLMs.
\ No newline at end of file
+`cs-mic-mcp` is a small [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that gives an MCP client a deterministic calculator. It evaluates expressions with the [CSMic](https://git.jordanwages.com/wagesj45/cs-mic) expression parser instead of asking a language model to do the arithmetic itself.
+
+It provides:
+
+- `calculate(expression)`: evaluate an expression.
+- `search(expression)`: find supported CSMic functions and their arguments. Use an empty search to list them all.
+- A function-reference resource for clients that support MCP resources.
+
+For example, a client can call `calculate` with an expression such as `sqrt(144)` or use `search` to discover the exact syntax of a function.
+
+## Requirements
+
+- The .NET 10 SDK to build or run from source.
+
+## Run locally with stdio
+
+Use this mode when the MCP client starts the server as a local subprocess. The server communicates only through standard input and output, so it does not listen on a network port.
+
+From the repository root:
+
+```bash
+dotnet run --project src/cs-mic-mcp -- --stdio
+```
+
+Configure your MCP client to launch that command. A typical command-based configuration looks like this (adjust the working directory or use an absolute project path if your client starts elsewhere):
+
+```json
+{
+  "command": "dotnet",
+  "args": ["run", "--project", "src/cs-mic-mcp", "--", "--stdio"],
+  "cwd": "/path/to/cs-mic-mcp"
+}
+```
+
+Do not write ordinary output to the terminal while using stdio mode: stdout is reserved for MCP messages.
+
+## Serve over HTTP
+
+Run without `--stdio` to host the MCP endpoint over HTTP:
+
+```bash
+dotnet run --project src/cs-mic-mcp
+```
+
+By default, the development profile listens on `http://localhost:5000`. Connect an HTTP-capable MCP client to:
+
+```
+http://localhost:5000/mcp
+```
+
+To use a different address or port, set ASP.NET Core's URL setting when starting the server:
+
+```bash
+ASPNETCORE_URLS=http://localhost:8080 dotnet run --project src/cs-mic-mcp
+```
+
+The MCP endpoint would then be `http://localhost:8080/mcp`.
+
+## Build and publish
+
+Build the project:
+
+```bash
+dotnet build src/cs-mic-mcp/cs-mic-mcp.csproj
+```
+
+Publish self-contained, single-file builds for the project's supported platforms:
+
+```bash
+dotnet msbuild src/cs-mic-mcp/cs-mic-mcp.csproj -t:PublishAll
+```
+
+The output is placed under `src/cs-mic-mcp/bin/Publish/`, with one folder per platform. Run the published executable with `--stdio` for local-process use, or without it for HTTP serving.
+
+## Notes
+
+This server enables permissive CORS for its HTTP endpoint so browser-based MCP clients can connect. If you expose it beyond your own machine, put it behind the authentication and network controls appropriate for your environment.