MCP-Server-Übersicht

Verbinde KI-Agenten über den Model-Context-Protocol-Server mit Nomadfiling — erfahre mehr über Protokoll, Transport, Authentifizierung und verfügbare Endpunkte.

curl -X POST "{API_BASE_URL}/mcp-server" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "init_001",
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "clientInfo": {
        "name": "acme-agent",
        "version": "1.0.0"
      }
    }
  }'

const response = await fetch("{API_BASE_URL}/mcp-server", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Accept": "application/json"
  },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: "init_001",
    method: "initialize",
    params: {
      protocolVersion: "2025-06-18",
      clientInfo: {
        name: "acme-agent",
        version: "1.0.0"
      }
    }
  })
})

const data = await response.json()
console.log(data)

{
  "jsonrpc": "2.0",
  "id": "init_001",
  "result": {
    "protocolVersion": "2025-06-18",
    "capabilities": {},
    "serverInfo": {
      "name": "nomadfiling-mcp",
      "version": "1.1.0"
    },
    "instructions": "NomadFiling MCP — manage US LLC filings (Form 5472/1120, Partnership, K-1, 8804/8805). Use get_form_schema first, then create_filing."
  }
}

curl -X POST "{API_BASE_URL}/mcp-server" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer nf_example_9xmk7q2r4b7m8n2p6t1v5c8a" \
  -d '{
    "jsonrpc": "2.0",
    "id": "tool_001",
    "method": "tools/call",
    "params": {
      "name": "get_form_schema",
      "arguments": {
        "formType": "form-5472-1120"
      }
    }
  }'

const response = await fetch("{API_BASE_URL}/mcp-server", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer nf_example_9xmk7q2r4b7m8n2p6t1v5c8a"
  },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: "tool_001",
    method: "tools/call",
    params: {
      name: "get_form_schema",
      arguments: {
        formType: "form-5472-1120"
      }
    }
  })
})

const data = await response.json()
console.log(data)

{
  "jsonrpc": "2.0",
  "id": "tool_001",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{"formType":"form-5472-1120","schema":{"type":"object"}}"
      }
    ],
    "structuredContent": {
      "formType": "form-5472-1120",
      "schema": {
        "type": "object"
      }
    }
  }
}

Agenten mit dem Nomadfiling-MCP-Server verbinden

Nomadfiling stellt einen Model-Context-Protocol-Server für KI-Agenten bereit, die Einreichungstools entdecken, Tool-Schemas lesen und Einreichungen über eine standardisierte JSON-RPC-Schnittstelle erstellen müssen. Der Server verwendet streamable HTTP-Transport und bleibt zwischen Anfragen zustandslos.

Authentifiziere nur tools/call-Anfragen. Methoden wie initialize, ping und tools/list funktionieren ohne Authentifizierung, sodass Clients Fähigkeiten entdecken können, bevor sie einen Login- oder API-Schlüssel-Ablauf anzeigen.

Serveridentität

Verwende diese Werte, wenn du MCP-Clients konfigurierst oder die initialize-Antwort prüfst.

baseUrlstring

Required

{API_BASE_URL}/mcp-server

runtimestring

Serverlose Laufzeitumgebung.

transportstring

Streamable HTTP.

sessionModelstring

Zustandslos. Der Server stützt sich nicht auf persistente Sitzungen zwischen Anfragen.

protocolVersionstring

2025-06-18

serverNamestring

nomadfiling-mcp

serverVersionstring

1.1.0

appUrlstring

https://app.nomadfiling.com

instructionsstring

NomadFiling MCP — manage US LLC filings (Form 5472/1120, Partnership, K-1, 8804/8805). Use get_form_schema first, then create_filing.

Wofür der Server gedacht ist

Der MCP-Server ist für agentengetriebene Einreichungs-Workflows ausgelegt. Ein Client verbindet sich typischerweise, liest die verfügbaren Tools, fordert das Schema für ein Formular an und sendet anschließend strukturierte Einreichungsdaten.

Damit eignet sich der Server gut für:

KI-Desktop-Clients wie Claude Desktop
Chat-Integrationen, die MCP-Verbindungen unterstützen
Eigene Agenten-Runtimes, die JSON-RPC über HTTP senden können
Interne Automatisierungen, die vor der Ausführung eine Tool-Entdeckung benötigen

Typischer Anfrageablauf

Die meisten Integrationen folgen derselben Sequenz, auch wenn der Client einen Teil davon für dich übernimmt.

Den MCP-Endpunkt verwenden

Sende JSON-RPC-Anfragen an den MCP-Root-Endpunkt. Wenn dein Client Server-Sent Events mit dem Header Accept auf text/event-stream anfordert, gibt derselbe Endpunkt SSE-formatierte Antworten zurück.

Ein erfolgreicher initialize-Aufruf bestätigt, dass Client und Server dieselbe Protokollversion sprechen können. Rufe danach tools/list auf, um Tool-Schemas zu entdecken, bevor du eine authentifizierte Tool-Ausführung versuchst.

Server-Sent Events anfordern

Verwende SSE, wenn dein MCP-Client event: message-Frames statt eines einfachen JSON-Bodys erwartet.

curl -X POST "{API_BASE_URL}/mcp-server" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": "ping_001",
    "method": "ping",
    "params": {}
  }'

const response = await fetch("{API_BASE_URL}/mcp-server", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Accept": "text/event-stream"
  },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: "ping_001",
    method: "ping",
    params: {}
  })
})

const text = await response.text()
console.log(text)

Die Event-Nutzlast ist als event: message formatiert, gefolgt von data: und dem JSON-RPC-Antwortkörper.

Tool-Aufrufe authentifizieren

Authentifiziere tools/call entweder mit einem NomadFiling-API-Schlüssel oder einem OAuth-2.1-Zugriffstoken. Beide Authentifizierungsmethoden verwenden den Header Authorization mit dem Schema Bearer.

Unterstützte Authentifizierungsmethoden

Verwende einen API-Schlüssel, wenn du die Integration steuerst und keinen OAuth-Zustimmungsablauf für Endnutzer benötigst. API-Schlüssel verwenden das Präfix nf_, und der Server prüft einen SHA-256-Hash gegen gespeicherte Schlüsseldatensätze.

authorizationHeaderstring

Authorization: Bearer nf_example_9xmk7q2r4b7m8n2p6t1v5c8a

verificationstring

Der Server hasht das vorgelegte Token mit SHA-256 und vergleicht es mit api_keys.key_hash.

expirystring

Pro Schlüssel konfigurierbar.

usageTrackingstring

Eine erfolgreiche Authentifizierung aktualisiert last_used_at.

Wenn du tools/call ohne gültige Anmeldedaten sendest, gibt der Server HTTP 401 zurück und fügt einen Header WWW-Authenticate hinzu. Behandle diese Antwort als Authentifizierungsaufforderung, nicht als Fehler auf Tool-Ebene.

Beispiel für einen authentifizierten Tool-Aufruf

Dieses Beispiel zeigt das Muster zum Aufrufen eines Tools nach der Entdeckung. Ersetze Tool-Namen und Argumente durch ein echtes Tool aus /de/api-reference/api/mcp-tools.

Ein erfolgreiches Tool-Ergebnis enthält sowohl eine Textnutzlast als auch structuredContent. Fehler auf Tool-Ebene verwenden eine fehlerförmige Tool-Nutzlast, während Fehler auf Protokollebene JSON-RPC-Fehler verwenden.

Die verfügbaren Endpunkte verstehen

Der MCP-Server stellt sowohl den zentralen JSON-RPC-Kanal als auch OAuth-Discovery-Endpunkte bereit.

OAuth- und MCP-Endpunkte

path

/.well-known/oauth-protected-resourceGET

Required

Gibt OAuth-Metadaten für geschützte Ressourcen gemäß RFC 9728 zurück.

path

/.well-known/oauth-authorization-serverGET

Required

Gibt OAuth-2.1-Authorization-Server-Metadaten zurück.

path

/.well-known/openid-configurationGET

Required

Gibt dieselben Authorization-Server-Metadaten über einen OpenID-Configuration-Pfad zurück.

path

/registerPOST

Required

Registriert OAuth-Clients dynamisch gemäß RFC 7591.

path

/authorizeGET

Required

Startet den Autorisierungsablauf und leitet zu https://app.nomadfiling.com/oauth/authorize weiter.

path

/approvePOST

Required

Genehmigt die OAuth-Zustimmung in einem frontendseitigen Ablauf, der das JWT des angemeldeten Benutzers verwendet.

path

/tokenPOST

Required

Stellt Token für die Grants authorization_code und refresh_token aus.

path

/POST

Required

Verarbeitet MCP-JSON-RPC-Anfragen und unterstützt SSE-Antworten.

CORS-Verhalten

Browserbasierte Clients können den Server direkt aufrufen. Die Function gibt permissiv gesetzte CORS-Header zurück und beantwortet OPTIONS-Preflight-Anfragen mit Status 200 und nur Headern.

Access-Control-Allow-Originstring

*

Access-Control-Allow-Methodsstring

GET, POST, OPTIONS, DELETE

Access-Control-Allow-Headersstring

authorization, x-client-info, apikey, content-type, mcp-session-id, mcp-protocol-version

Access-Control-Expose-Headersstring

mcp-session-id, www-authenticate

JSON-RPC-Methoden und Verhalten

Der Server implementiert eine fokussierte MCP-Methodenschnittstelle. Einige Methoden sind informativ, während tools/call authentifizierte Aktionen ausführt.

Unterstützte Methoden

initializemethod

Keine Authentifizierung erforderlich. Gibt protocolVersion, capabilities, serverInfo und instructions zurück.

pingmethod

Keine Authentifizierung erforderlich. Gibt ein leeres Objekt zurück.

notifications/initializedmethod

Keine Authentifizierung erforderlich. Gibt HTTP 202 zurück.

notifications/cancelledmethod

Keine Authentifizierung erforderlich. Gibt HTTP 202 zurück.

tools/listmethod

Keine Authentifizierung erforderlich. Gibt alle Tool-Schemas zurück.

tools/callmethod

Authentifizierung erforderlich. Leitet die Ausführung an das benannte Tool weiter.

resources/listmethod

Gibt ein leeres Ergebnis zurück.

prompts/listmethod

Gibt ein leeres Ergebnis zurück.

Fehlerbehandlung

Verwende HTTP-Status und JSON-RPC-Fehlercodes zusammen. Parse-Fehler treten vor der Methodenzuordnung auf, Autorisierungsfehler, wenn eine geschützte Tool-Anfrage den Server erreicht.

Bedingung	HTTP-Status	JSON-RPC-Code	Bedeutung
Ungültiger JSON-Body	400	-32700	Parse-Fehler
Unbekannte Methode	200	-32601	Methode nicht gefunden
Nicht authentifizierter geschützter Tool-Aufruf	401	-32001	Unauthorized

Form der Tool-Antwort

Eine erfolgreiche Tool-Ausführung gibt MCP-Inhalt plus eine strukturierte Nutzlast zurück, die dein Client direkt parsen kann.

contentarray

Required

Ein Array von Nachrichtenteilen. Erfolgreiche Tool-Antworten enthalten ein Textelement, dessen Feld text einen JSON-String enthält.

content[].typestring

Required

Bei aktuellen Tool-Antworten ist der Wert text.

content[].textstring

Required

Eine menschenlesbare oder serialisierte JSON-Nutzlast.

structuredContentobject

Required

Eine maschinenlesbare Darstellung desselben Ergebnisses.

Wenn ein Tool auf Anwendungsebene fehlschlägt, gibt der Server eine MCP-Tool-Fehlernutzlast statt eines erfolgreichen structuredContent-Ergebnisses zurück.

isErrorboolean

Required

Wird bei Fehlern auf Tool-Ebene auf true gesetzt.

contentarray

Required

Enthält mindestens eine Textnachricht, die den Fehler beschreibt.

Token-Formate und Laufzeiten

Token-Präfixe helfen Clients, den Anmeldedatentyp zu unterscheiden, bevor sie eine Anfrage senden. Der Server speichert sensibles Token-Material als SHA-256-Hashes statt als Rohgeheimnisse.

Bestandsübersicht der Anmeldedaten

Anmeldedaten	Präfix	Laufzeit
API-Schlüssel	`nf_`	Konfigurierbar
OAuth-Client-ID	`mcp_client_`	Permanent
OAuth-Client-Secret	`mcp_secret_`	Permanent
Autorisierungscode	`mcp_code_`	5 Minuten
Zugriffstoken	`mcp_at_`	1 Stunde
Refresh-Token	`mcp_rt_`	30 Tage

Empfohlenes Integrationsmuster

Rufe get_form_schema vor create_filing auf. Diese Reihenfolge entspricht den Serveranweisungen und reduziert Tool-Aufruffehler durch fehlende oder fehlerhafte Einreichungsfelder.

Verbindung initialisieren

Sende initialize, um die Protokollversion zu bestätigen und die zurückgegebenen Servermetadaten zu erfassen.

Dein Client ist bereit für die Entdeckung, wenn die Antwort protocolVersion auf 2025-06-18 und serverInfo.name auf nomadfiling-mcp setzt.

Tools entdecken

Rufe tools/list ohne Authentifizierung auf, wenn dein Client anonyme Entdeckung unterstützt, oder mit Authentifizierung, wenn deine Integration einen einzigen authentifizierten Kanal bevorzugt.

Erfolg sieht aus wie ein JSON-RPC-Ergebnis mit den verfügbaren Tool-Definitionen.

Formularschema abrufen

Rufe tools/call mit dem Tool get_form_schema auf, bevor du Daten sendest.

Erfolg sieht aus wie ein Tool-Ergebnis mit structuredContent, das die erwartete Einreichungsform für das ausgewählte Formular beschreibt.

Einreichung erstellen

Rufe tools/call erneut mit create_filing und einer Nutzlast auf, die dem gerade abgerufenen Schema entspricht.

Eine erfolgreiche Übermittlung gibt ein MCP-Tool-Ergebnis statt eines Protokollfehlers zurück.

MCP-Server-Übersicht

Agenten mit dem Nomadfiling-MCP-Server verbinden

Serveridentität

Wofür der Server gedacht ist

Typischer Anfrageablauf

Den MCP-Endpunkt verwenden

Server-Sent Events anfordern

Tool-Aufrufe authentifizieren

Unterstützte Authentifizierungsmethoden

Beispiel für einen authentifizierten Tool-Aufruf

Die verfügbaren Endpunkte verstehen

OAuth- und MCP-Endpunkte

CORS-Verhalten

JSON-RPC-Methoden und Verhalten

Unterstützte Methoden

Fehlerbehandlung

Form der Tool-Antwort

Token-Formate und Laufzeiten

Bestandsübersicht der Anmeldedaten

Empfohlenes Integrationsmuster

Häufig gestellte Fragen

Verwandte Seiten