Secani MCP

Secani MCP lets an approved AI client work with Secani through the Model Context Protocol. The server is designed for authenticated compliance workflows, with explicit human approval for changes.

What Secani MCP Provides

Secani MCP is a remote MCP server for Secani users. It uses Streamable HTTP and OAuth 2.0 bearer authentication through WorkOS.

The production endpoint is:

https://mcp.secani.com/mcp

The server exposes a small, progressive tool surface:

• whoami discovers visible organizations, workspaces, governance scopes, and effective access.
• discover_capabilities finds capabilities relevant to an intent or skill; load_skill loads the corresponding workflow guidance.
• inspect_schema, search_entities, inspect_entity, and expand_entity form the universal read plane. The first adapter supports V3 workspace objects.
• create_inventory_object and revise_inventory_object create inventory objects or new immutable revisions.
• Evidence tools find, inspect, create, version, qualify, and assign evidence. Files up to 512 KiB can be sent inline; larger files up to 10 MiB use a short-lived, hash-bound upload.
• connection_check and human_approval_number_test remain available as isolated diagnostic tools.

Connection Details

The protected-resource metadata endpoint tells your MCP client which WorkOS authorization server to use. Configure the server URL in your client, then complete the OAuth flow in the client when prompted.

Connect an MCP Client

Generic remote MCP configuration

For clients that accept a remote MCP server definition, add:

{
  "mcpServers": {
    "secani": {
      "url": "https://mcp.secani.com/mcp"
    }
  }
}

The exact configuration file and OAuth UI depend on your client. Use the name Secani or secani, make sure the URL is exactly https://mcp.secani.com/mcp, and approve the WorkOS sign-in request.

Claude Code

Add Secani as a remote HTTP MCP server:

claude mcp add --transport http secani https://mcp.secani.com/mcp

Start Claude Code and open its MCP management flow to authorize the connection. The browser sign-in is part of OAuth; do not paste a bearer token into your project configuration.

Codex CLI

Add the server with the HTTP URL:

codex mcp add secani --url https://mcp.secani.com/mcp

When Codex detects OAuth support, follow the browser authorization flow and return to the CLI.

Cursor

Add the server to your MCP configuration:

{
  "mcpServers": {
    "secani": {
      "url": "https://mcp.secani.com/mcp"
    }
  }
}

Start the server from Cursor's MCP panel. Cursor should ask you to authenticate before protected tools are available.

ChatGPT custom connector

If your ChatGPT workspace supports custom remote MCP connectors:

1. Enable Developer mode in the connector settings.
2. Create a custom connector named Secani.
3. Set the MCP server URL to https://mcp.secani.com/mcp.
4. Select OAuth authentication.
5. Complete the WorkOS authorization flow.

Availability and menu names depend on your ChatGPT plan and workspace configuration.

Available Tools

whoami

Call this first to discover visible workspaces, up to 50 authorized governance scopes per workspace, baseline readiness, and the connector's effective read-only or write state.

discover_capabilities

Optionally describe the current intent with intent or select a registered skill. The response contains only relevant capabilities available in the current connector mode, unavailable skill tools, and compact toolset counts. Convex still enforces authorization on every subsequent call.

load_skill

Loads versioned Secani workflow guidance such as explore-workspace-context or curate-evidence, including focused reference links. A skill orchestrates public tools but grants no additional permissions. Secani Eve uses the same skills and tool names.

inspect_schema

Loads object classes and agent-oriented field metadata for one authorized governance scope. The response includes volatility, retrieval, and sensitivity hints from the existing V3 Agent Context contract.

search_entities

Runs the existing hybrid lexical and semantic search inside one authorized governance-scope baseline and returns ranked references instead of complete records. Decisive references should be inspected before reasoning or proposing a change.

inspect_entity

Loads compact, integrity-checked current state for one entity included in the authorized governance-scope baseline and advertises optional context without loading it into the model context.

expand_entity

Loads one bounded segment advertised by inspect_entity: authorized relations, volatile state, or protection need. Other domains remain behind dedicated safe projections instead of raw-record access.

create_inventory_object

Creates exactly one new object (for example an application) in the inventory of the given workspace after explicit approval. The server uses the same V3 domain command as the Secani inventory dialog, writes an audit event with an AI actor, and never adds the object to a governance scope automatically.

Input:

{
  "organizationSlug": "acme",
  "workspaceSlug": "cloud-platform",
  "governanceScopeId": "<from whoami>",
  "objectClassCode": "application",
  "name": "test",
  "description": "optional",
  "requestId": "<uuid>"
}

The server asks for an MCP form approval before writing. Declining or cancelling changes nothing. Clients that cannot answer form approvals receive an error and nothing is written. requestId is the idempotency key: repeating the call with the same ID and content returns the existing object instead of a duplicate. The governance scope is used only for authorization (inventory.create on that scope); read-only connectors cannot run the action.

revise_inventory_object

Creates a new immutable revision of an existing inventory object after approval. The call requires the object ID plus the current revision ID and content hash returned by inspect_entity. It can change or remove the name, description, and revision-relevant attributes. If current state changes between inspection and writing, Secani returns STALE_CURRENT instead of overwriting another change.

Evidence workflow

The Evidence surface keeps four domain states distinct:

1. list_evidence_artifacts and inspect_evidence_artifact locate existing evidence and its current immutable version.
2. create_evidence_artifact creates an HTTPS reference or file; add_evidence_version updates its content by adding a version without overwriting history.
3. record_evidence_fact qualifies one pinned artifact version as a supported statement about a pinned object revision.
4. link_evidence_usage assigns that fact to a pinned framework requirement. Only this successful step constitutes a domain assignment.

list_framework_bindings, list_requirement_targets, and list_evidence_subjects provide the required current pins. All four Evidence writes require approval, are idempotent by requestId, and record AI provenance. Files up to 512 KiB use canonical base64. For larger files, the action returns a two-minute upload ticket after approval; the client sends the unchanged bytes with the same OAuth bearer. Secani verifies exact size and SHA-256 before storing anything.

connection_check

Use this read-only tool to verify the connection after OAuth authorization.

Input:

{
  "echo": "optional diagnostic text"
}

The response confirms the authenticated Secani user and MCP client identity. It is useful as the first call after connecting a new client.

human_approval_number_test

Use this tool to test a complete human-in-the-loop workflow. It proposes an integer and asks the user to accept, decline, or cancel the change.

Input:

{
  "value": 42,
  "fieldLabel": "MCP-Testwert"
}

After approval, Secani stores the value in the Settings dialog test field. If the client cannot display MCP form elicitation, the requested value is treated as approved by the server's compatibility fallback. The tool still requires an authenticated Secani user and a configured test secret.

Recommended Workflow

1. Add https://mcp.secani.com/mcp to your client.
2. Complete OAuth authorization with the WorkOS account that should access Secani.
3. Call whoami and select a visible workspace and baseline-ready governance scope.
4. Use discover_capabilities for the current intent.
5. Inspect the schema when field meaning is unclear; for read tasks navigate with search_entities → inspect_entity → expand_entity.
6. Use create_inventory_object for new objects or, after a current inspection, revise_inventory_object for changes.
7. Load curate-evidence for evidence work, preserve every returned revision and hash, and keep artifact, fact, and usage distinct.
8. Use connection_check or human_approval_number_test only for its specific diagnostic purpose, and approve changes only for intentional tests.

Troubleshooting

The client reports 401 Unauthorized

The server requires a valid OAuth bearer token for MCP requests. Re-open the client's MCP authorization flow and confirm that the account has completed WorkOS sign-in. Do not replace the MCP URL with the OAuth issuer URL.

OAuth discovery fails

Verify that the client is using the production endpoint and can reach:

https://mcp.secani.com/.well-known/oauth-protected-resource/mcp

The metadata response points the client to the correct authorization server and declares the required openid scope.

The approval prompt does not appear

The client may not support MCP form elicitation. Update the client if possible. Secani has a compatibility fallback for this test tool, but you should still review the proposed value before allowing the call to continue.

The endpoint opens as a web page

The MCP endpoint is a machine-to-machine transport, not a human-facing dashboard. Use an MCP client and the OAuth flow rather than a normal browser session. Human-readable MCP information is available at secani.com/docs/mcp.

Security Guidance

• Verify the hostname before authorizing: mcp.secani.com is the official Secani MCP host.
• Use OAuth through your MCP client; never commit or paste bearer tokens into source files, prompts, or issue trackers.
• Review the client name, requested account, and scope before approving access.
• Treat inventory, Evidence, and diagnostic write actions as mutating tools and keep form approvals enabled.
• Keep human confirmation enabled for workflows that can make changes.
• Only connect MCP clients and extensions you trust. An authorized client can send requests as the connected Secani user.