Add a custom MCP connector, then read its open-source rule order

A provider: mcp entry needs a url, and transport is http (the default) or sse. The other providers each need their own address: base_url for http, endpoint for graphql, spec for openapi and postman, app for composio and pipedream (connectors keys).

• slug: The name every rule and grant uses
• provider: How Kortix reaches the app
• url: The MCP server's address
• transport: http or sse
• authorization_strategy: Whether accounts belong to the project or to each person
• policies: The connector's base rules
• policy_sets: Named rule sets an agent can be given
• sensitive: Whether unmatched calls wait for a person

enabled: false turns the connector off. auth says how Kortix sends the credential, and the credential lives in Kortix, never in the file. headers are static request headers, at most 32, and their values are plain text in Git, so a token pasted there is a token in the repository.

A policy set is a named group of rules on one connector, and an agent binds it by name. The docs' example project gives a helpdesk connector a read-only set that runs get_* and blocks *, then binds that set to one agent (example project). A set name is lowercase letters, digits, - and _, at most 64 characters, and not base. A connector can carry at most 32 sets of 200 rules each, and channel connectors carry none. Five slugs are reserved for the built-in connectors: kortix_slack, kortix_teams, kortix_email, kortix_telegram and computer.

Kortix decides each connector call in four places, and in each list the first rule that matches decides. The project policies come first. Then the calling agent's policy set on that connector, agents.<name>.policy_sets. Then the connector's own policies, its base rules. Then no rule matched, where a sensitive connector holds the call and otherwise policy.default_mode answers (connector rules and approvals). A set or a base rule cannot loosen a project rule. A set can loosen a base rule for its agent, and a set the connector does not define blocks every call of that agent on it.

A project rule is the one place a team can say that nothing deletes anything. It holds on every server, including the one somebody adds next month. A connector's base rules are the local habit: reads run, the rest asks. The agent's set is the exception, granted by name to one agent. Read in that order, a call has one answer, and the answer is the same on Tuesday as it was on the day of the review.

A delete on Linear matches *.delete* at the project level, so it is blocked. The Linear entry's own * rule says require_approval, and that rule is never read, because level one already matched. This is the part a client that shows you a URL and a sign-in cannot give you. The connector's rule looks permissive, the project's rule is what runs, and only the file shows both.

linear.create_issue is the second case. The project rule names it and asks for approval. The connector's * rule would also ask. Same outcome, different level, and the difference matters the day someone loosens the connector's base rules, because the project rule still holds.

The Notion entry puts a condition to work. create_page runs when parent.database_id matches 3f2a1c*, and every condition must hold. A page created anywhere else falls through to the entry's * rule and waits for a person. match is a glob over <connector-slug>.<tool>, case-insensitive, and a condition is { arg, match, negate }, with arg a dot path into the call's arguments.

Sentry shows the fourth level on its own. The entry sets sensitive: true, so a call that no rule matches needs approval, reads included. A read on that connector waits, which is the right default for a server whose tools nobody has read yet.

authorization_strategy is project (the connector's accounts belong to the project) or user (each person connects their own account); the default is project. An account is private to one person or shared with the project, and a private account works only in its owner's private sessions. Automations never use a private account; they need an account shared with the whole project. A connector a schedule will call therefore needs a shared account before the schedule exists, and whose permissions a call carries takes the choice apart.

Approval gates you set. Off until you set them, so a file with no rules is a file that runs everything policy.default_mode allows. kortix validate prints each issue with its file, line and column (when kortix.yaml has a problem), and it does not check policy or policies (connector rules and approvals). When Kortix syncs connectors, it skips a malformed rule and reports it as a connector sync error. A rule with a typo passes the check a reader trusts most, then disappears at sync.

So a clean run is the start. Five checks after it:

1. Name the level. For the action you care about, say which of the four decides it. If two could match, the higher one wins and the lower one is decoration.
2. Send one read. It should run, and it should appear in the session's record.
3. Send one write that a rule holds. The agent's turn should pause, and the approval should name the action and the account.
4. Change one argument, then approve. The changed call needs a new approval, because an approval covers one exact action.
5. Check the account. A call from a schedule or a trigger must run as a shared account, or it will not run at all.

The entry does not hold the tool list, which the server publishes, or the account, which is a live connection. It holds the decision about both: which actions may run, and which account strategy applies. What an agent can reach covers the three layers together.

The example manifest is a working file: three MCP connectors, the project rules that outrank them and one agent grant, in a public example repository. It ships a small checker that fails when a rule is malformed, which covers the gap kortix validate leaves. Clone it, replace the servers with yours, and the first review is a diff.