Skip to content
Back to search

concierge

πŸš€ Universal SDK for building next-gen MCP servers

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/concierge-hq--concierge/badge.svg)](/listings/concierge-hq--concierge)

HTML

<a href="/listings/concierge-hq--concierge"><img src="/api/listings/concierge-hq--concierge/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

> [!NOTE] > Concierge requires Python 3.9+. We recommend installing with [uv](https://docs.astral.sh/uv/) for faster dependency resolution, but pip works just as well.

pip install concierge-sdk

**Scaffold a new project:**

concierge init my-store    # Generate a ready to run project
cd my-store                # Enter project
python main.py             # Start the MCP server

**Or wrap an existing MCP server** two lines, nothing else changes:

# Before
from mcp.server.fastmcp import FastMCP
app = FastMCP("my-server")

# After: just wrap it
from concierge import Concierge
app = Concierge(FastMCP("my-server"))

> [!TIP] > Concierge works at the MCP protocol level. It dynamically changes which tools are returned by `tools/list` based on the current workflow step. The agent and client don't need to know Concierge exists, they just see fewer, more relevant tools at each point.

<br />

from concierge import Concierge
from mcp.server.fastmcp import FastMCP

app = Concierge(FastMCP("my-server"))

# Your @app.tool() decorators stay exactly the same.
# You can additionally add app.stages and app.transitions.

> [!NOTE] > The wrap and go gives you progressive tool disclosure immediately. Add `app.stages` and `app.transitions` when you want full workflow control, no code changes required.

<br />

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md Β· README Β· 223 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. <!-- omit in toc -->
  3. <picture>
  4. <img width="900" alt="Concierge Banner" src="assets/concierge-banner.png" />
  5. </picture>
  6. # Concierge AI πŸš€
  7. <strong>The fabric for reliable MCP servers and AI applications.</strong>
  8. [![Docs](https://img.shields.io/badge/docs-getconcierge.app-blue)](https://docs.getconcierge.app)
  9. [![Discord](https://img.shields.io/badge/community-discord-5865F2?logo=discord&logoColor=white)](https://discord.gg/Y3ayRa33Pg)
  10. [![PyPI - Version](https://img.shields.io/pypi/v/concierge-sdk.svg)](https://pypi.org/project/concierge-sdk)
  11. [![Python](https://img.shields.io/badge/python-3.9+-8B5CF6?logo=python&logoColor=white)](https://pypi.org/project/concierge-sdk)
  12. </div>
  13. The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is a standardized way to connect AI agents to tools. Instead of exposing a flat list of every tool on every request, Concierge progressively discloses only what's relevant. Concierge guarantees deterministic results and reliable tool invocation.
  14. ## Getting Started
  15. > [!NOTE]
  16. > Concierge requires Python 3.9+. We recommend installing with [uv](https://docs.astral.sh/uv/) for faster dependency resolution, but pip works just as well.
  17. ```bash
  18. pip install concierge-sdk
  19. ```
  20. **Scaffold a new project:**
  21. ```bash
  22. concierge init my-store # Generate a ready to run project
  23. cd my-store # Enter project
  24. python main.py # Start the MCP server
  25. ```
  26. **Or wrap an existing MCP server** two lines, nothing else changes:
  27. ```python
  28. # Before
  29. from mcp.server.fastmcp import FastMCP
  30. app = FastMCP("my-server")
  31. # After: just wrap it
  32. from concierge import Concierge
  33. app = Concierge(FastMCP("my-server"))
  34. ```
  35. > [!TIP]
  36. > Concierge works at the MCP protocol level. It dynamically changes which tools are returned by `tools/list` based on the current workflow step. The agent and client don't need to know Concierge exists, they just see fewer, more relevant tools at each point.
  37. <br />
  38. ```python
  39. from concierge import Concierge
  40. from mcp.server.fastmcp import FastMCP
  41. app = Concierge(FastMCP("my-server"))
  42. # Your @app.tool() decorators stay exactly the same.
  43. # You can additionally add app.stages and app.transitions.
  44. ```
  45. > [!NOTE]
  46. > The wrap and go gives you progressive tool disclosure immediately. Add `app.stages` and `app.transitions` when you want full workflow control, no code changes required.
  47. <br />
  48. ## Usage
  49. ### Group tools into steps
  50. Instead of exposing everything at once, group related tools together. Only the current step's tools are visible to the agent:
  51. ```python
  52. app.stages = {
  53. "browse": ["search_products", "view_product"],
  54. "cart": ["add_to_cart", "remove_from_cart", "view_cart"],
  55. "checkout": ["apply_coupon", "complete_purchase"],
  56. }
  57. ```
  58. ### Define transitions
  59. Control which steps can follow which. The agent moves forward (or backward) only along paths you allow:
  60. ```python
  61. app.transitions = {
  62. "browse": ["cart"], # Can only move to cart
  63. "cart": ["browse", "checkout"], # Can go back or proceed
  64. "checkout": [], # Terminal step
  65. }
  66. ```
  67. <details>
  68. <summary><b>Share state between steps</b></summary>
  69. <br>
  70. Pass data between workflow steps without round-tripping through the LLM. State is session-scoped and works across distributed replicas:
  71. ```python
  72. # In the "browse" step - save a selection
  73. app.set_state("selected_product", {"id": "p1", "name": "Laptop"})
  74. # In the "cart" step retrieve it directly
  75. product = app.get_state("selected_product")
  76. ```
  77. </details>
  78. <details>
  79. <summary><b>Scale with semantic search</b></summary>
  80. <br>
  81. When you have hundreds of tools, enable semantic search to collapse your entire API behind two meta-tools:
  82. ```python
  83. from concierge import Concierge, Config, ProviderType
  84. app = Concierge("large-api", config=Config(
  85. provider_type=ProviderType.SEARCH,
  86. max_results=5,
  87. ))
  88. ```
  89. No matter how many tools you register, the agent only ever sees:
  90. ```
  91. search_tools(query: str) β†’ Find tools by description
  92. call_tool(tool_name: str, args: dict) β†’ Execute a discovered tool
  93. ```
  94. </details>
  95. ### Run over HTTP
  96. Concierge supports multiple transports. Use streamable HTTP for web deployments:
  97. ```python
  98. # Streamable HTTP (recommended for web)
  99. http_app = app.streamable_http_app()
  100. # Or run over stdio (default, for CLI-based clients)
  101. app.run()
  102. ```
  103. > [!TIP]
  104. > All of the above: stages, transitions, state, semantic search are optional and independent. Use any combination. Start simple and add structure as your workflow grows.
  105. ## Features
  106. | | |
  107. |:--|:--|
  108. | **Progressive Disclosure**: Only expose the tools that matter right now. Fewer tools in context means less confusion and lower cost. | **Enforced Tool Ordering**: Define which tools unlock which. The agent follows your business logic, not its own guesses. |
  109. | **Shared State**: Pass data between workflow steps server-side. No tool-call chaining through the LLM, no re-injecting data into prompts. | **Semantic Search**: For large APIs (100+ tools), collapse everything behind two meta-tools. The agent searches by description, then invokes. |
  110. | **Protocol Compatible**: Wraps any MCP server. Your existing `@app.tool()` decorators, resources, and prompts work unchanged. | **Session Isolation**: Each conversation gets its own workflow state. Atomic, consistent, works across distributed replicas. |
  111. | **Multiple Transports**: Run over stdio, streamable HTTP, or SSE. Deploy anywhere: serverless, containers, bare metal. | **Scaffolding CLI**: `concierge init` generates a ready to run project with tools, stages, and transitions wired up ready to go. |
  112. ## Example Concierge Application
  113. A complete e-commerce workflow in under 30 lines:
  114. ```python
  115. from concierge import Concierge
  116. app = Concierge("shopping")
  117. @app.tool()
  118. def search_products(query: str) -> dict:
  119. """Search the product catalog."""
  120. return {"products": [{"id": "p1", "name": "Laptop", "price": 999}]}
  121. @app.tool()
  122. def add_to_cart(product_id: str) -> dict:
  123. """Add a product to the cart."""
  124. cart = app.get_state("cart", [])
  125. cart.append(product_id)
  126. app.set_state("cart", cart)
  127. return {"cart": cart}
  128. @app.tool()
  129. def checkout(payment_method: str) -> dict:
  130. """Complete the purchase."""
  131. cart = app.get_state("cart", [])
  132. return {"order_id": "ORD-123", "items": len(cart), "status": "confirmed"}
  133. app.stages = {
  134. "browse": ["search_products"],
  135. "cart": ["add_to_cart"],
  136. "checkout": ["checkout"],
  137. }
  138. app.transitions = {
  139. "browse": ["cart"],
  140. "cart": ["browse", "checkout"],
  141. "checkout": [],
  142. }
  143. app.run() # Start over stdio
  144. ```
  145. The agent starts at `browse`. It can move to `cart`, then to `checkout`. It cannot call `checkout` from `browse`. Concierge enforces this at the protocol level, no prompt engineering required.
  146. <br />
  147. ## Documentation
  148. Full guides, API reference, and deployment patterns are available at **[docs.getconcierge.app](https://docs.getconcierge.app)**.
  149. <br />
  150. ## Community
  151. - [Discord](https://discord.gg/Y3ayRa33Pg): Ask questions, share what you're building, get help.
  152. - [Issues](https://github.com/concierge-hq/concierge/issues): Report bugs or request features.
  153. - [Discussions](https://github.com/concierge-hq/concierge/discussions): Longer form discussions and RFCs.
  154. ---
  155. <p align="left">
  156. We are building the agentic web. Come <a href="mailto:arnav@getconcierge.app">join us</a>.
  157. </p>
  158. ## License
  159. [Apache License 2.0](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.