Conciergent

Give your MCP tools a chat face. Connect Conciergent to any Model Context Protocol server and it becomes a Slack or LINE bot that can actually do things, with per-user OAuth handled inside the conversation, an approval gate before destructive tools run, and one structured reply that renders natively on every surface.

Conciergent pairs with its sister project openapi-mcp-gateway, which turns any REST API into MCP tools. Together they take one or more OpenAPI specs all the way to a chatbot your users can talk to.

• Any MCP Server, or an OpenAPI Spec Directly. Point Conciergent at an MCP URL, or set gateway.enabled and drop in a spec. It embeds openapi-mcp-gateway in-process, no second server to run.
• In-Chat OAuth. When a tool needs authorization, Conciergent shows the link in the chat, then stores and refreshes the token. The user never leaves the conversation.
• Human-in-the-Loop. Any tool the server marks destructive pauses behind a Confirm / Cancel card before it runs.
• Surface-Agnostic Rich Replies. The agent emits one structured reply, and each surface renders it natively.

Quick Start

Two things are yours to set up once. Register a chat app with a public webhook URL, and have a Redis and a Postgres to run against (the Docker path below provides both). Everything else is ${ENV_VAR} in one YAML file.

1. Install and Scaffold

uv add conciergent
uv run conciergent init

uv run conciergent init writes an annotated conciergent.yml, deep-merged over the shipped defaults so you set only what you change.

2. Configure Your MCP Tools

Conciergent reaches your tools two ways, and you can use both at once.

Connect an MCP Server

List any MCP server URL under agent.mcp_servers. The scaffolded conciergent.yml already has the surface and store set up around it.

# conciergent.yml
agent:
  model: openai:gpt-4o-mini
  system_prompt: |
    You are a helpful assistant. Use your tools to answer the user's requests.
  mcp_servers:
    - http://localhost:9000/mcp
    - https://another-server.example.com/mcp

If a server uses OAuth, Conciergent runs the in-chat authorization handoff the first time a tool needs it, with no extra config.

Or Embed an OpenAPI Spec

Add the gateway extra and let Conciergent embed openapi-mcp-gateway in-process, so a spec becomes MCP tools with no second server to run.

uv add "conciergent[gateway]"

gateway:
  enabled: true
  specs:
    - name: petstore
      spec: https://petstore3.swagger.io/api/v3/openapi.json
      base_url: https://petstore3.swagger.io/api/v3
    - name: internal
      spec: ./internal-api.json

Each spec is served at /{name}/mcp and wired into the agent for you, alongside anything already in agent.mcp_servers. A complete runnable config lives at examples/openapi-chat.yml.

A spec entry mirrors openapi-mcp-gateway's per-server config, so you can add exposure: dynamic for a large spec (the agent sees three meta-tools instead of one per endpoint), a policy filter, or auth (bearer, api_key, or oauth2). An oauth2 spec runs the same in-chat OAuth handoff, so each user authorizes their own account before its tools run.

3. Connect Your Chat App

Conciergent replies in direct messages, and the in-chat OAuth happens there too. Register the app once and set its request URLs, where {your-public-url} is your public host.

The MCP OAuth return (/oauth/mcp/callback) is registered with the MCP server automatically, so it is not something you set in a dashboard. For local development, run a tunnel (cloudflared / ngrok) in front of the port and use its URL as {your-public-url} and as server.url.

4. Run

Two ways, depending on whether you already have Redis and Postgres.

Against your own Redis and Postgres:

createdb conciergent      # the database must exist, and Conciergent will create its tables on first run
uv run conciergent run

Or with Docker, which brings up Redis, Postgres, and the app together and needs no uv:

cp examples/openapi-chat.yml conciergent.yml     # or use your own
docker compose up

Secrets stay in the environment. conciergent.yml reads the Slack, LINE, and provider credentials through ${...}, so nothing sensitive is committed. The app serves on port 8000, so put your tunnel in front of it and set server.url to the tunnel URL.

Configuration

Conciergent reads one conciergent.yml, merged over the shipped defaults, so you set only what you change. ${VAR} / ${VAR:-default} resolve in any string field.

Three model providers ship in the box. Set agent.model to a provider:model string and export that provider's API key.

The shipped default is openai:gpt-4o-mini. Any model the provider offers works, so pick the current one from its docs.

Localizing Text

Button labels, prompts, and greetings are not config. They live in a locale catalog, picked from each user's Slack or LINE language. Set locales_dir to a directory of {lang}.yml files to rebrand or translate. examples/locales/en.yml is the full English catalog to start from.

The Reply Model

The agent never speaks Slack or LINE. It emits one of three shapes, and each surface renders it natively.

• str for plain text.
• Card for a header, up to six text sections, an optional hero image, a footnote, up to five link buttons, and up to three suggestion quick-replies.
• Carousel for one to four option cards the user picks between, plus a fallback card.

A suggestion is the interactive primitive. Tapping one posts its prompt back to the agent as if the user had typed it. The field descriptions on these models are the agent's structured-output schema, so the model fills them in directly.

Extending

The paved road above needs no code. These are for teams who want to go further.

class Surface(abc.ABC):
    @abc.abstractmethod
    def build_routers(self, context: SurfaceContext) -> list[fastapi.APIRouter]:
        """Return the webhook and auxiliary routes this platform needs."""

from conciergent import App, MessageStore, CredentialStore
from conciergent.agent.runner import ChatRunner
from conciergent.surfaces.slack.app import Slack

message_store = MessageStore.from_url('redis://localhost:6379/0')
credential_store = CredentialStore.from_url('postgresql+asyncpg://localhost/conciergent')

app = App(
    runner=ChatRunner(
        model='openai:gpt-4o-mini',
        system_prompt='You are a helpful assistant.',
        mcp_servers=['http://localhost:9000/mcp'],
        credential_store=credential_store,
        redirect_uri='https://your-public-url/oauth/mcp/callback',
    ),
    surfaces=[Slack(signing_secret='...', bot_token='xoxb-...')],
    message_store=message_store,
    credential_store=credential_store,
    base_url='https://your-public-url',
)
app.run()

License

MIT